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.

Public developers, partners on a private beta, or internal service consumers each need different framing — auth complexity, SLAs, and support paths differ. State the audience explicitly so contributors don't accidentally publish internal-only endpoints to the public reference.

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.

One copyable curl against a no-auth or sandbox endpoint that returns a real 200 in under a second. Verify it actually runs from a clean shell — missing escape characters in JSON payloads are the most common copy-paste failure.

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.

Document every distinct error code the API returns: HTTP status, application-level error code, message shape, and the recommended client behavior (retry, surface to user, escalate). Include 401 vs 403 disambiguation — confusing them is a top integration bug.

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.

Webhook handling, pagination over large result sets, idempotency-key usage on retried POSTs, and bulk import patterns. Each scenario gets a short narrative plus a runnable example.

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.

Broken object-level authorization (BOLA), excessive data exposure, mass-assignment, and missing rate limits cover most real incidents. Tell consumers what your API does to prevent each, and what they need to do on their end.

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.

State plan-level monthly quotas, what happens at the threshold (soft warn, hard block, overage billing), and how consumers monitor consumption mid-cycle. Surprise overage charges are a top churn driver.

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.

Status page, X/Twitter handle, LinkedIn page, and any tagged hashtags. Status page should be the canonical incident channel — point consumers there before social.

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.

DevRel or tech-writing lead reviews the rendered site (not the source) for broken links, stale screenshots, and copy-pasteable snippets that actually run. Sign-off goes here; reviewer notes capture anything punted to a follow-up ticket.