API documentation, explained
Good API documentation has several layers. A reference describes every endpoint, field, type, status code and error. Guides explain authentication, pagination and common workflows. A quickstart gets a developer to a first successful call in minutes. A changelog records what changed and when.
Reference docs are usually generated from an OpenAPI or GraphQL schema, rendered by tools such as Redoc, Swagger UI or Stoplight, so they stay in sync with the contract. Guides and examples are written by hand, and they are where most drift happens.
- Show complete, copyable requests and responses in several languages.
- Document every error with its cause and fix.
- Mark deprecated fields and link to migration guides with dates.
Documentation describes intended behavior, not actual behavior. When the implementation changes without the docs, or the docs change without announcing it, consumers find out in production. Generating docs from the same spec you test against keeps them honest. See the API documentation guide.
Related terms
- OpenAPI Specification: The OpenAPI Specification is a standard, language-agnostic format (YAML or JSON) for describing HTTP APIs: their paths, operations, parameters, schemas and authentication.
- API endpoint: An API endpoint is a specific address, usually a URL path combined with an HTTP method, where a client sends requests to perform one operation on an API.
- API deprecation: API deprecation is the formal announcement that an endpoint, field or version is going away, with a timeline for clients to migrate before it is removed.