API Documentation

Definition

For an API consumed by people you do not control, documentation is not a supporting artefact; it is the interface through which the product is evaluated and adopted. An excellent API with poor documentation loses to a mediocre one with excellent documentation, consistently.

What good documentation contains

• A working request in the first screen. Copy-paste, with real credentials if possible. Time to first successful call is the metric that predicts adoption.
• Reference generated from the schema, so it cannot drift from the implementation.
• Guides organised by task, not by endpoint. Nobody wants to know about POST /charges; they want to know how to take a payment.
• Errors documented as thoroughly as successes, including what causes each and what to do about it. This is what integrators spend most of their time on and it is almost always the thinnest section.
• Idempotency, retry and rate-limit semantics stated explicitly, because integrators will otherwise assume the most convenient interpretation and build a bug.
• Versioning and deprecation policy, so a business can commit to the integration.
• Realistic examples, including the awkward cases — partial failures, asynchronous outcomes, webhooks arriving out of order.

Industry example

Stripe's documentation is widely treated as the reference standard, and the transferable observation is why: it documents the failure and retry semantics with the same care as the happy path. Idempotency keys, at-least-once webhook delivery, out-of-order event arrival and reconciliation are explained as first-class parts of the interface rather than as caveats.

That is a design decision as much as a writing one. Because the API's dominant driver is correctness under retry, the documentation must teach the integrator to build a correct integration — otherwise the provider's careful idempotency guarantees are defeated by a consumer that assumed exactly-once delivery and shipped a double-fulfilment bug.

Documentation that explains the failure model is a resilience mechanism, not a courtesy.

Failure scenarios

• Hand-written reference documentation that drifts from the implementation.
• Examples that do not run, because they were written against an earlier version.
• Undocumented error codes, so integrators handle only the errors they happened to hit in testing.
• Rate limits discovered in production, because they were never stated.
• Documentation as a separate team's responsibility, arriving weeks after the API changes.

Interview question

"What would you document about an API's failure behaviour, and why is that more important than documenting its success behaviour?"