How to document a REST API

Good API documentation begins with the job a reader must complete. A frontend developer needs inputs, authentication and response shapes. An operator needs failure signals. An integrator needs a runnable example and the limits around it.

Write for those decisions. A long description cannot compensate for missing parameter requirements or an unexplained 422 response.

• Name the task each operation completes.
• State authentication requirements beside the operation.
• Describe failure cases that callers must handle.
• Use examples that match the schema.

Use OpenAPI fields for methods, paths, parameters, request bodies and responses. Structured information can drive a reference UI, validation, a request builder and client generation; prose alone cannot.

Give operations stable IDs. They become useful identifiers for generated functions and internal links even when the display summary changes. This OpenAPI path fragment belongs under paths; include a full document header and response definitions when importing it.

paths:
  /payments/{paymentId}:
    get:
      operationId: getPayment
      parameters:
        - in: path
          name: paymentId
          required: true
          schema:
            type: string

Document the response a caller wants and the responses it must survive. Authentication failure, validation failure, missing resources, conflicts and server errors often matter more during integration than a second success example.

For each important status, describe when it happens and provide a representative body. Keep the status, content type, schema and example consistent.

• 201 for a created resource when creation is synchronous.
• 400 for malformed input.
• 401 when authentication is missing or invalid.
• 403 when identity is known but access is denied.
• 422 when the syntax is valid but domain validation fails.

Examples should look like values a caller will actually send, while avoiding secrets or personal data. Use a coherent set of identifiers across the request and response so the example reads as one scenario.

Validate examples during review. A stale example that violates the current schema teaches the reader the wrong contract.

POST /payments
{
  "orderId": "ord_123",
  "amount": 4900,
  "currency": "EUR"
}

Documentation drifts when method, path and schemas are copied into unrelated systems. Prefer a workflow in which documentation, request execution and generated clients read the same normalized definition.

Review documentation changes alongside API contract changes. A new required field, status or authentication rule is part of the feature, not follow-up writing work.

• Import or edit the contract.
• Review the rendered operation.
• Run a representative request.
• Regenerate integration code when schemas change.