Writing API reference

The anatomy of an endpoint page, and how to keep it in sync with your OpenAPI spec.

1 min read

Reference documentation answers one question: what exactly does this endpoint do? Readers scan it, so it has to be complete, consistent and predictable.

Anatomy of an endpoint#

Every endpoint page has the same parts, in the same order:

Summary. One sentence, starting with a verb.
Request. Method, path, auth, parameters and body schema.
Example. A runnable request in at least curl and one SDK language.
Response. Status codes, schema and a real example body.
Errors. The specific errors this endpoint can return.

Start from the spec#

Write descriptions and examples in the OpenAPI file, then generate the reference from it. This keeps a single source of truth.

reference/openapi.yaml

paths:
  /v1/projects:
    post:
      summary: Create a project
      description: Creates a project in your workspace and returns it.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewProject"
            example:
              name: Billing docs
              visibility: private
      responses:
        "201":
          description: The project was created.
        "422":
          description: The request body failed validation.

Document errors properly#

A generic "returns 400 on bad input" helps nobody. Document each error with its code, cause and fix.

Status	Code	Cause	Fix
401	`invalid_api_key`	Missing or revoked key	Send `Authorization: Bearer <key>`
422	`validation_failed`	Body failed schema validation	Check the `errors` array in the response
429	`rate_limited`	Too many requests	Retry after the `Retry-After` seconds

Show the whole request#

Create a project

const response = await fetch("https://api.example.com/v1/projects", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Billing docs", visibility: "private" }),
});
console.log(await response.json());

Try a mock request yourself in the API Playground.

Was this page helpful?

PreviousStyle guide Next Release notes that get read