How to write great API documentation

Who reads API docs, and why

API documentation has several audiences with different questions. An evaluator wants to know whether the API can do the job. A new integrator wants a first successful call. A working developer wants the exact shape of one parameter. A maintainer wants to know what changed and what will break. Good docs answer each question in the place that audience looks, rather than mixing everything into one long page. See API documentation for a short definition.

Increasingly there is a fifth reader: an AI coding assistant that a developer has asked to write the integration. Assistants rely on the same things humans do, only more literally. Exact parameter names, explicit units, complete examples and a clearly marked current version help them produce correct code; ambiguity produces confident mistakes. Writing for a careful machine reader is a good test of whether a page is precise enough for people too.

The path to a first successful call

Time to first successful call is the most useful single measure of onboarding docs. Walk the path yourself with a fresh account and note every point where you had to guess. Common friction points:

• Finding where to create a key, and which key (test or live) to use.
• Authentication details buried in a separate page with no example header.
• Base URLs, regions or required headers that the quickstart never mentions.
• A first example that depends on data the new account does not have yet.

Fix each one in the quickstart itself. Link authentication, rate limits and error handling from the first page, because these are the next three things every new integrator hits.

Reference vs guides

The most useful structural decision is to separate kinds of documentation. The Diátaxis framework names four: tutorials, how-to guides, reference and explanation. For APIs that usually becomes:

• Quickstart (tutorial). From zero to a successful call in a few minutes: get a test key, make one request, see the response.
• Guides (how-to). Task-oriented pages such as "accept a payment", "handle webhooks" or "paginate through results", each a complete path through several endpoints.
• Reference. Every endpoint, parameter, field, enum value, error code and limit, complete and exact. Usually generated from a specification.
• Concepts (explanation). Authentication, object lifecycles, idempotency, pagination, versioning: the ideas the guides and reference assume.

Reference without guides leaves developers assembling workflows by trial and error. Guides without complete reference leave them guessing at edge cases. You need both, cross-linked.

Generate reference from OpenAPI

Hand-written reference drifts from the implementation. Describing the API in OpenAPI and generating reference pages from it keeps one source of truth that also powers mock servers, client SDKs, validation and OpenAPI diff checks in CI. Make the spec worth rendering:

• Write a real description for every operation, parameter and schema property, not just a restated name.
• Document units, formats, defaults, allowed values and nullability explicitly.
• Include example values that are realistic and internally consistent.
• List every possible response status and its error body, not only 200.
• Mark deprecated operations and properties with deprecated: true and a description that names the replacement.

parameters:
  - name: limit
    in: query
    description: Maximum number of invoices to return. Defaults to 10.
    schema:
      type: integer
      minimum: 1
      maximum: 100
      default: 10

Then test the spec against the running API. A spec that does not match the implementation is worse than none, because readers trust it.

Examples that actually run

Developers copy examples first and read prose second. Make every example something they can paste and run:

• Show a complete request (method, URL, headers, body) and the complete response, including headers that matter.
• Provide examples in the languages your users write, ideally using your official SDKs, plus a curl version.
• Use test-mode credentials and realistic data, never real secrets.
• Show error examples too: what a validation failure or rate-limit response looks like.
• Run examples in CI so they break when the API changes, instead of quietly going stale.

curl https://api.example.com/v1/invoices?limit=2 \
  -H "Authorization: Bearer $EXAMPLE_TEST_KEY"

Changelogs developers can act on

A changelog is documentation for people who already integrated. Each entry should answer: what changed, which endpoints and fields it affects, whether it is breaking, which API or SDK version it applies to, and what the reader needs to do.

• Date every entry and group by version.
• Label each change as added, changed, deprecated, removed, fixed or security, a convention popularised by Keep a Changelog.
• Call out breaking changes explicitly, including behavioral ones such as a changed default, unit or sort order, which are easy to omit because the schema did not change.
• Link each breaking change to its migration guide.
• Offer a feed or email subscription so developers do not have to check manually.

Deprecation notices and migration guides

When something is going away, the docs carry most of the message. A good deprecation notice states what is deprecated, the replacement, the sunset date, and a link to a migration guide, and it appears in the reference page itself, the changelog and in machine-readable form through Deprecation and Sunset headers. See how to deprecate an API and the Sunset header.

The migration guide should map every old operation and field to its replacement, list behavioral differences explicitly, and show before-and-after code. Even then, each consumer still has to find and change their own call sites, which is the expensive part of any API migration. Some providers now go further than instructions and hand consumers ready-made changes; Releo, for example, opens migration pull requests verified against replayed traffic.

Keeping docs current

Treat docs as part of the product: store them with the code, review them in the same pull request as the change, lint the OpenAPI document, test examples in CI, and check links. Add a feedback link on each page and read what comes in. Docs fit naturally into the API lifecycle: written at design time, updated with each change, and retired alongside the version they describe. Strong docs complement good API design; they cannot rescue a confusing one.

Frequently asked questions

Related guides

• API design best practices
• How to deprecate an API
• OpenAPI diff: detecting breaking changes in CI