API documentation: what developers actually read

API documentation is the interface to your interface. However good the API, a developer's experience of it is the docs — and the way docs are used is consistent and worth designing around: search for the thing, copy a working example, adapt it, leave. Almost nobody reads the introduction.

That behaviour explains why beautifully organised documentation with no copyable examples fails, and why a plain page with a correct curl command for every endpoint succeeds. Optimise for the person who arrives at one page from a search engine with a specific problem.

What every endpoint page needs

• A complete, runnable example — a real request with real-looking values, not a schema fragment. The single most-used element on any API documentation page is the copy button.
• The full response, including the fields you consider boring. Developers map response shapes; partial examples cause bugs.
• Every parameter with type, whether it is required, the default, and the constraint. Optional is not an answer; optional, defaults to 20, maximum 100 is.
• Errors this endpoint actually returns, with the code and what causes it. This is the most-skipped section and the most-needed one at three in the morning.
• Authentication shown in the example rather than described elsewhere.
• Rate limits, or a link to them — the ground covered in rate limiting.

The surrounding pieces

1. A getting-started page that takes somebody from nothing to one successful call, with no branching. Not a tour of concepts — one path.
2. Authentication explained once, properly, including how to rotate a credential and what an expired one looks like.
3. A changelog with dates. This is what an integrator checks when something broke yesterday, and its absence is why they email you instead.
4. A machine-readable specification — OpenAPI — because it generates clients, powers try-it consoles and keeps the docs honest. Generating docs from the spec removes the class of error where the docs describe last year's API.
5. Guides for the two or three real jobs people use the API for, alongside the reference. Reference answers what does this endpoint do; a guide answers how do I sync my orders.

Test the examples automatically. Documentation drifts silently and the first person to notice is a customer with a broken integration and a poor opinion of your engineering. Running the documented examples against the real API in continuous integration is a half day of work and converts your docs from a description into a check.

What to leave out

Long conceptual introductions nobody reaches, marketing language in a reference, and internal terminology that means nothing to somebody outside the company. Also worth avoiding: documenting endpoints you intend to change next month — mark them experimental explicitly rather than letting somebody build on them, because they will.

Where this sits

Ettex API publishes its own reference, and the conventions behind it are described in rest api, with events in webhook. For anything you build against it, the practices in api integration apply.

Being clear: we do not host or generate documentation for your APIs — this is not a docs platform. What is described here is how to write documentation people can use, whichever tool you write it in.