Non-reference content in API docs

By Tom Johnson / @tomjohnson
idratherbewriting.com


Slides available at
idratherbewriting.com/nonref-content-api-docs

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

idratherbewriting.com/learnapidoc

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

API Key

Examples: Sendgrid

HMAC

Examples: AWS

OAuth

Examples: Dropbox | TwitterBitly

4. Status and error codes

Examples: Flickr | Clearbit | Twitter | Mailchimp | Context.io

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

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

Questions?

The end

Tom Johnson
idratherbewriting.com
@tomjohnson
[email protected]