API Documentation Rules

API documentation is the product for a developer evaluating whether to integrate — a confusing or incomplete reference loses the integration before a single line of their code gets written, regardless of how good the API itself is. Write for a developer who has ten minutes to decide if this is worth their time, not for someone already committed to reading every page.

Every endpoint documented with a runnable example

• Give every single endpoint a complete, copy-pasteable request example (curl at minimum, ideally in the caller's likely language too) that actually runs against the real API as documented — a pseudocode snippet that "shows the idea" but doesn't execute forces the developer to debug the documentation itself before they can debug their integration.
• Test documented examples against the live API as part of the release process — an example that drifts out of sync with the actual API (a renamed field, a changed required parameter) is worse than no example, because it fails in a way that looks like the developer's mistake.

Request and response examples with realistic data

• Show a full example request and its full example response together for every endpoint, using realistic-looking values (real-shaped IDs, plausible names and amounts) rather than placeholder junk ("string", 123, "foo") that gives no sense of the actual data shape.
• Include a response example for at least one common error case per endpoint alongside the success case — a developer integrating error handling needs to see the actual error shape, not just infer it from a generic error section elsewhere in the docs.

Error catalog with causes

• Maintain a complete catalog of every error code/status the API can return, with the specific condition that triggers each one and what the caller should do about it — "400: Bad Request" with no further detail forces the developer to guess or contact support for something the docs should answer directly.
• Distinguish retryable errors from non-retryable ones explicitly (a rate limit should say so and give a retry-after signal; a validation error should say so and specify what to fix) — conflating them leads integrators to either retry things that will never succeed or give up on things a simple retry would fix.

Auth explained first

• Put authentication setup as the very first thing in the documentation, before any endpoint reference — no example in the rest of the docs is runnable until auth works, so an integrator without working auth is blocked on everything else regardless of how good later sections are.
• Give a complete, working auth example (how to obtain a key/token, exactly how to attach it to a request) rather than just naming the auth scheme ("uses Bearer token auth") and assuming the developer knows the specifics for this particular API.

Changelog for breaking changes

• Maintain a changelog specifically calling out breaking changes (removed fields, changed required parameters, changed default behavior) separately from routine additions — a developer scanning for "will this break my integration" shouldn't have to read every changelog entry to find the ones that matter.
• Version the API explicitly (a version in the URL, a header, or a date-based version scheme) and document the deprecation and sunset timeline for any prior version being retired, with enough lead time for integrators to migrate before it's turned off.

Quickstart under 5 minutes

• Write a quickstart that takes a new developer from zero to one successful API call in under five minutes, covering exactly the minimum path (get a key, make one call, see a real response) — a quickstart that front-loads architecture explanation or covers every auth option before the first working example loses developers before they see anything work.
• Keep the quickstart's example separate from and simpler than the full reference documentation — the quickstart's job is a fast win, not comprehensive coverage; link to the full reference for everything beyond the first call.

Docs generated from source of truth

• Generate the endpoint reference (parameters, types, required/optional, response schema) from the actual API definition (OpenAPI/Swagger spec, or equivalent schema the server enforces) rather than hand-written prose that has to be manually kept in sync — hand-maintained reference docs reliably drift from the real API as it evolves, and drifted docs are worse than no docs because they're actively misleading.
• Keep the hand-written narrative content (quickstart, guides, conceptual explanation) separate from the generated reference, so regenerating the reference from the spec never clobbers the prose that required human judgment to write.