Intro to API documentation

a one-hour crash course version of my full-day workshop

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides: idratherbewriting.com/slides/crash_course.html
Course: idratherbewriting.com/learnapidoc/

APIs allow systems to interact

Image from Brent 2.0 on Flickr

API example: Flight booking sites

The essence: Requests and responses

REST API growth phenomenal

Sample scenario: Retrieve weather

Choose an API

Submit a request

curl common for requests


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

Sections in API endpoint docs

  1. Resource description
  2. Endpoints and methods
  3. Parameters
  4. Request example
  5. Response example and schema

Note: API terminology varies drastically from site to site.

Mock example

Real example — Sendgrid

Unique characteristics of API docs

OpenAPI specification

Swagger UI Petstore Demo

API conceptual topics

  • Getting started (Hello World)
  • Authorization
  • Status and error codes
  • Rate limiting and thresholds
  • Code samples and tutorials
  • SDKs and sample apps

Getting started

Authorization

Status and error codes

SDKs and sample apps

Auth/pub tools developers prefer

The Docs as Code model

Example - Gatsby, Github

Characteristics of docs as code

  • Lightweight markup (e.g., Markdown)
  • Static site generators (e.g., Hugo)
  • IDE-like text editor (e.g., Atom)
  • Version control to manage content (e.g., Git)
  • Build from server (e.g., Netlify)

Common API doc tools

A culture of forking and building

Real-time demonstration

Demonstration of docs-as-code publishing...

Why few API writers attend STC

  • Tools are different (Expo mostly irrelevant)
  • Developer audience different
  • Doc'ing code isn't a task-based paradigm
  • Structure refers to OAS, not DITA
  • Technical ramp-up is steep
  • Culture is more unconference style
  • Open-source tools are the norm

Getting an API doc job

  • Familiarity with 1-2 programming languages or other technical foundations (sample job)
  • Experience writing docs for a developer audience (show portfolio)

Tip: Build a portfolio through Season of Docs.

Solving the biggest problems

... the biggest problems with API documentation were also the ones requiring the most technical expertise to solve. Completing, clarifying, and correcting documentation require deep, authoritative knowledge of the API’s implementation. This makes accomplishing these tasks difficult for non-developers or recent contributors to a project. — Martin Robillard and Gias Uddin

Spectrum of involvement

Questions?

The end

Tom Johnson
— idratherbewriting.com
— @tomjohnson
— [email protected]