API reference
ay-pee-eye REF-rens
Comprehensive documentation of every endpoint, parameter, and response in an API, serving as the definitive technical specification.
An API reference is the complete technical documentation of every endpoint, method, parameter, request format, and response in an API. It is the source of truth. When a developer needs to know exactly what parameters an endpoint accepts, what the response looks like, and what errors can occur, they check the API reference.
Good API references are generated from the API specification (OpenAPI/Swagger) so they stay in sync with the actual API. Manual API references inevitably become outdated. Auto-generated references with human-written descriptions and examples strike the best balance.
The best API references include interactive examples. Stripe and Twilio let developers make real API calls directly from the reference page, see the request and response, and copy the code into their application. Many teams also generate SDK client libraries from the same specification.
Examples
A company auto-generates its API reference.
The engineering team maintains an OpenAPI specification. The docs pipeline generates the reference from the spec on every deploy. Every endpoint has auto-generated request/response schemas. The technical writer adds human-written descriptions and examples.
An interactive API reference improves DX.
The reference page for each endpoint has a 'Try it' button. Developers enter parameters, click the button, and see the actual API response. They copy the generated code sample in their preferred language. Time to understand an endpoint drops from 10 minutes to 2.
A developer discovers an undocumented parameter.
A developer finds that the API accepts a parameter not listed in the reference. They report it. The docs team adds it to the reference and the OpenAPI spec. This gap would not have existed with auto-generated documentation.
Frequently asked questions
What is the difference between API reference and API guide?
The API reference documents every endpoint technically (parameters, responses, errors). An API guide explains how to accomplish tasks using the API (authentication flow, common workflows, best practices). References are exhaustive. Guides are task-oriented. Both are necessary.
Should API references be auto-generated?
Yes, from an OpenAPI specification. This ensures the reference always matches the actual API. But auto-generation alone is not enough. Add human-written descriptions, examples, and usage notes. The best references combine automation for accuracy with human writing for clarity.
Related terms
Written resources that explain how to use a product, including guides, tutorials, API references, and troubleshooting information.
A concise, step-by-step guide that gets a developer from zero to a working implementation in the shortest time possible.
How easy, productive, and enjoyable it is for developers to use a product, from documentation to API design to error messages.
Want the complete playbook?
Picks and Shovels is the definitive guide to developer marketing. Amazon #1 bestseller with practical strategies from 30 years of marketing to developers.