Non-reference content in API docs

By Tom Johnson / @tomjohnson

Slides available at

What I'll talk about

  1. Overviews
  2. Getting started
  3. Authentication and authorization
  4. Status and error codes
  5. Rate limiting and thresholds
  1. Code samples and tutorials
  2. SDKs and sample apps
  3. Quick reference
  4. Best practices with the API
  5. Glossary
  6. FAQs

Where to find more information

1. Overview

Examples: Lyft | Sendgrid | IBM Cloud

Address the "why"

“Startups fail when they are not solving a market problem. We were not solving a large enough problem that we could universally serve with a scalable solution. We had great technology, great data on shopping behavior, great reputation as a thought leader, great expertise, great advisors, etc, but what we didn’t have was technology or business model that solved a pain point in a scalable way.” — Treehouse Logic, The Top 20 Reasons Startups Fail

2. Getting started

Examples: Paypal | IBM Cloud | Twitter | Google AdsenseLyft

Run in Postman

Compare with Hello World tutorials

TTHW = "Time to hello world"

3. Authorization and authentication


Examples: Sendgrid


Examples: AWS


Examples: Dropbox | TwitterBitly

4. Status and error codes

Examples: Flickr | Clearbit | Twitter | Mailchimp |

5. Rate limiting and thresholds

Examples: GitHub | Linkedin | Bitly

6. Code samples and tutorials

Examples: Eventful | Twilio | Mailchimp | IBM Cloud

Cover common scenarios

While a developer’s guide should walk a developer through the basic usage of an API and its functionality, it can’t cover every possible use of that API in a coherent way. That is where articles and tutorials come in, to teach developers tangential or specialized uses of an API, like combining it with another service, framework, or API. The Six Pillars of Complete Developer Documentation

7. SDKs and sample apps

Examples: Paypal | Heroku | Google Cloud | Amazon | Citygrid | IBM Cloud

8. Quick reference

Examples: Eventful | Shopify | Parse

9. Best practices

Examples: Threat Stack | Mailchimp | Coinbase

Sample best practice topics

pagination, time ranges, fault tolerance, cache values, connectivity, timeouts, downtime, SSL, versions, testing and validation, exports, languages, number handling, expanding resources, notifications, etc.

10. Glossary

Examples: Lyft | Yext | Apigee

11. FAQ

Examples: Smugmug | NYTimes


The end

Tom Johnson
[email protected]