API Documentation Checklist

Two to three paragraphs at the top of the docs site: what the API does, what problems it solves, and what it explicitly does not do. Link to a one-page architecture diagram if the surface area is non-trivial. Keep this in sync with the marketing site — drift between the two confuses prospects.

State the semver version (e.g., v2.4.0) and the wire-level versioning convention — URI path (/v2/), Accept header, or a custom header. Mismatched conventions between docs and SDK are a frequent source of support tickets.

Walk a new developer from sign-up to first successful call: account creation, dashboard tour, sandbox vs. production environments, base URLs for each. Time-to-first-call is the metric that matters; aim for under five minutes.

Cover where keys are issued, how to scope them, how to rotate, and how to revoke. Warn against committing keys to git — link to gitleaks or GitGuardian setup. Show the Authorization: Bearer header pattern in a copyable snippet.

Generate from source annotations (e.g., springdoc-openapi, drf-spectacular, fastapi) rather than hand-editing YAML — drift between code and spec is a perennial bug source. Validate with Spectral or openapi-cli lint before publishing.

Each field needs a type, whether it is required, an example value, and a one-line description. Mark deprecated fields explicitly with the version they will be removed in. Stoplight, Redoc, and Scalar all render OpenAPI schemas well — pick one and stick with it.

Pick the three to five flows that account for most real usage — pull them from analytics or top support tickets. A guide is a sequenced narrative (auth → fetch → transform → submit), not a list of endpoints.

Tabbed samples per language, all showing the same call. Run each sample end-to-end before publishing — stale samples that don't compile are worse than no sample. If you ship SDKs, the samples should call through the SDK, not raw HTTP.

State the minimum TLS version (1.2+ is the modern floor; 1.3 preferred), HSTS posture, and that plain HTTP requests are rejected rather than redirected. Note any IP allow-listing options for partners.

For each supported scheme: when to use it, the full flow with sequence diagram, token lifetime, and refresh behavior. PKCE is required for public clients on OAuth 2.1 — call this out explicitly.

State the bucket size and refill rate, the scope (per key, per IP, per tenant), and the response headers consumers should read — typically X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After on a 429.

Show an exponential-backoff-with-jitter snippet. Many integrations retry tight without jitter and stampede the rate limiter the moment it resets — which is worse than the original spike.

Email, in-app ticket form, or Zendesk portal — include the request-ID/trace-ID consumers should attach so support can pull logs without a back-and-forth. State response-time SLAs by plan tier.

Discourse, GitHub Discussions, or a dedicated Slack/Discord — pick one canonical place rather than scattering across channels. Confirm a DevRel or engineer is staffed to answer there; an unanswered forum is worse than no forum.

State the versioning convention (URI path vs. header), the support window for old majors (e.g., previous major supported for 12 months after a new major), and how clients pin to a version. Be explicit about what counts as a breaking change — adding a required request field counts; adding a response field generally doesn't.

Diff the new OpenAPI spec against the previous published version. Removed endpoints, removed response fields, narrowed enum values, newly-required request fields, and changed status-code semantics all count as breaking. If anything qualifies, follow the breaking-change path below.

Side-by-side before/after for each breaking change, with the deprecation date, the removal date, and a code-mod or sed snippet where possible. Email the deprecation notice to active API consumers — relying on docs alone misses the long tail.

Dated entries grouped as Added / Changed / Deprecated / Removed / Fixed / Security (Keep a Changelog format). Link each entry to the relevant endpoint reference page so consumers can jump from "what changed" to "how it works now" in one click.