API documentation / How-to
Document an API from first request to reference
Explain setup, requests, responses, and failure recovery together.
Start with an outcome
Choose one realistic task and a safe test environment. State required access, the base URL, the API version, and how the reader obtains a credential. Use a placeholder or environment variable in examples; never publish a live secret.
Build the reference
For each operation, document its purpose, HTTP method and path, authentication, parameters, request body, response fields, and errors. Explain required values, constraints, defaults, and pagination when relevant. Separate an example value from a guaranteed rule.
Make success observable
Show a minimal request and representative response, then explain the field that proves the task succeeded. Identify what varies between test and production. Stripe’s reference is a useful example of making sandbox and version context visible.
Test more than the happy path
Verify the sample in the documented version. Check missing credentials, invalid input, permission failures, and rate limits where applicable. Do not invent error codes. Link recovery steps to the actual errors the product returns.
Sources & further reading
Original guidance and examples by TechWriter, informed by these resources.