Conceptual content in API docs

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides available at
idratherbewriting.com/slides/conceptual_content_api_docs.html

7 conceptual topics to cover

  1. Product overview
  2. Getting started
  3. Authentication and authorization
  4. Status and error codes
  5. Rate limiting and thresholds
  6. Quick reference
  7. SDKs (software development kits)

Activity 6a: Judge conceptual content and decide which is best

Evaluate why — use inductive reasoning

Product overview

Addressing 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 ..., 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

Example 1: Spotify

Example 2: Hootsuite

Example 3: Watson Assistant

Key principles

  • Don't assume everyone already knows the who, what, why, where, and how of your API
  • Provide high-level details about workflows, authentication, endpoints, etc.
  • Link to your Getting Started topic

API getting started

Compare with Hello World tutorials

Example 1: Mailchimp

Example 2: Paypal

Example 3: Google

Key principles

  • Define the simplest possible end-to-end steps to get started — link out to more details
  • Simplify account setup or other required assets or configurations

Tip: Use Run in Postman

API authentication and authorization

API Key

HMAC

OAuth

Example 1: Sendgrid

Example 2: Twitter

Example 3: AWS

Key principles

  • Don't include unnecessary details about how the authorization works
  • Provide a code sample
  • Describe correct usage — such as public versus private tokens in client-side code

API status and error codes

Response header in curl

curl -I -X GET 'https://api.openweathermap.org/data/2.5/weather?zip=95050&units=imperial&appid=APIKEY'

HTTP/1.1 200 OK
Server: openresty
Date: Mon, 02 Apr 2018 01:14:13 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 441
Connection: keep-alive
X-Cache-Key: /data/2.5/weather?units=imperial&zip=95050
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST

Headers in Postman

Example 1: Clearbit

Example 2: Twitter

Example 3: Mailchimp

Key principles

  • Help users recover from errors
  • Make error messages findable through search

API rate limiting and thresholds

Example 1: GitHub

Example 2: Linkedin

Example 3: Bitly

Key principles

  • Explain how to check current/remaining counts
  • List information by subscription tier

API quick reference

Example 1: Eventful

Example 2: Parse

Example 3: Veracode

API quick reference

Key principles

  • Provide an at-a-glance experience to help users understand the whole
  • Link the quick reference to the full details

SDKs (Software Development Kits)

Example 1: SAP SDKs

Example 2: Paypal SDKs

Example 3: Facebook SDKs

Key principles with SDKs

  • Explain how to integrate the SDK
  • Assume audience is familiar with language
  • Explain how to get the sample app working

Questions?