REST API Documentation: Best Practices, Template, Examples

Good REST API documentation answers four questions fast: how do I authenticate, what endpoints exist, what exactly do I send, and what comes back (including errors). The current standard way to write it is an OpenAPI description (version 3.2 is the latest, published September 2025, with a 3.2.1 patch in September 2026), rendered with a tool like Swagger UI, Redoc or Scalar, plus a hand-written getting-started guide. Below are the documentation practices that matter most, a copy-paste REST API documentation template, a documentation example in OpenAPI, and the tools that turn it into a site.

What REST API documentation must include

Treat this as the minimum standard. If any item is missing, developers end up emailing support or reading your source code.

1. Overview and base URL: what the API does, https://api.example.com/v1, environments (sandbox vs production).
2. Authentication: how to get a key or token, which header carries it, scopes, and a working example request.
3. Endpoint reference: for every endpoint, method + path, description, path/query parameters, request body schema, response schemas per status code.
4. Examples: a real request and a real response for every endpoint, in curl at minimum.
5. Errors: the error format, every error code you return, and what the client should do about each.
6. Pagination, filtering and sorting rules, written once and applied everywhere.
7. Rate limits: the limits, the headers that report them, and what 429 looks like.
8. Versioning and changelog: how versions work, what changed, and deprecation dates.
9. SDKs and tools: links to official client libraries and a Postman/Insomnia collection or OpenAPI file to import.

10 REST API documentation best practices

1. Write the OpenAPI description first, and generate from it

An OpenAPI file is a machine-readable contract. One file gives you rendered docs, mock servers, client SDKs, request validation and contract tests. Keep it in the same repo as the code and update it in the same pull request as the endpoint. Many frameworks generate it from code (FastAPI, NestJS, Django REST framework with drf-spectacular; see our Swagger for Python Django guide), which keeps it from drifting.

2. Start with a 5-minute quickstart

The reference tells people what's possible; the quickstart gets them to a first successful call. Show: get a key, run one curl, see a response. Put it at the top of the docs.

3. Give every endpoint a real example

Schema tables alone aren't enough. Show a full request and the exact response, with realistic values ("email": "ada@example.com", not "string"). OpenAPI examples fields render directly in most tools.

4. Document errors as carefully as success

List every status code an endpoint can return. Use one error format across the API; RFC 9457 problem details (application/problem+json) is the standard choice. Our REST API JSON examples show a full validation-error body, and the 400 Bad Request guide covers the most common client error.

5. Make authentication copy-pasteable

Show the exact header (Authorization: Bearer <token>), where to create the token, and the error you get when it's wrong. Most first-call failures are auth failures.

6. Explain conventions once

Field naming (snake_case or camelCase), date format (ISO 8601 in UTC), ID type, pagination style and idempotency keys belong on one "Conventions" page that every endpoint links to.

7. Add code samples in the languages your users use

curl plus the top two languages of your users (usually JavaScript and Python). Generate them from OpenAPI where possible so they stay correct, and test them in CI.

8. Version the docs with the API

Publish docs per API version, keep a dated changelog, and mark deprecated endpoints and fields in the spec (deprecated: true) with a removal date.

9. Lint the spec in CI

Linters such as Spectral and Redocly CLI catch missing descriptions, missing examples, inconsistent naming and broken $refs before they ship. Encode your style guide as lint rules.

10. Test the docs like code

Run every example request against a staging environment on each release. A wrong example is worse than none.

REST API standards and guidelines worth following

There is no single official "REST API standard". The building blocks are IETF RFCs, and several large companies publish design guidelines you can adopt instead of writing your own:

Source	What it covers
RFC 9110	HTTP semantics: methods, status codes, headers
RFC 9457	JSON error format (problem details)
OpenAPI Specification	Format for describing REST APIs
Microsoft REST API Guidelines	Naming, versioning, long-running operations, errors
Google API Improvement Proposals (AIP)	Resource-oriented design, standard methods, pagination
Zalando RESTful API Guidelines	Detailed MUST/SHOULD rules, JSON conventions

Pick one guideline, note deviations, and enforce it with a linter.

REST API documentation template

Use this structure for each endpoint page. It works in Markdown, a docs site, or a wiki.

## Create an article

`POST /v1/articles`

Creates a new article owned by the authenticated user.

### Authentication
Bearer token with the `articles:write` scope.

### Request body (application/json)
| Field   | Type     | Required | Description                 |
|---------|----------|----------|-----------------------------|
| title   | string   | yes      | 1-200 characters            |
| body    | string   | yes      | Markdown                    |
| tags    | string[] | no       | Up to 10 tags               |

### Example request
curl -X POST https://api.example.com/v1/articles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Hello", "body": "First post"}'

### Responses
| Status | Meaning                          |
|--------|----------------------------------|
| 201    | Created. Returns the article.    |
| 401    | Missing or invalid token.        |
| 422    | Validation failed (see errors).  |
| 429    | Rate limited. See Retry-After.   |

### Example response (201)
{ "id": "art_101", "title": "Hello", "body": "First post", "createdAt": "2026-10-11T09:30:00Z" }

REST API documentation example in OpenAPI

The same endpoint as an OpenAPI description. This uses the 3.1 version string because, as of October 2026, it has the widest tool support; 3.2 is a superset you can move to once your tools support it (Swagger UI and Editor added 3.2 support in April 2026).

openapi: 3.1.1
info:
  title: Example Articles API
  version: 1.0.0
servers:
  - url: https://api.example.com/v1
security:
  - bearerAuth: []
paths:
  /articles:
    post:
      summary: Create an article
      operationId: createArticle
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewArticle'
            example:
              title: Hello
              body: First post
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Article'
        '422':
          description: Validation failed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    NewArticle:
      type: object
      required: [title, body]
      properties:
        title: { type: string, minLength: 1, maxLength: 200 }
        body: { type: string }
        tags: { type: array, items: { type: string }, maxItems: 10 }
    Article:
      allOf:
        - $ref: '#/components/schemas/NewArticle'
        - type: object
          properties:
            id: { type: string, example: art_101 }
            createdAt: { type: string, format: date-time }
    Problem:
      type: object
      properties:
        type: { type: string }
        title: { type: string }
        status: { type: integer }
        detail: { type: string }

What 3.2 adds, if you need it: a reworked Tag Object for nested navigation, the HTTP QUERY method, additionalOperations for other methods, and first-class description of streaming responses such as Server-Sent Events (OpenAPI 3.2 spec).

Tools that render REST API docs

Tool	Type	Notes
Swagger UI	Open source	Interactive "try it out" console; the classic default
Redoc	Open source (paid Redocly platform)	Clean three-panel reference layout
Scalar	Open source (paid hosting)	Modern reference with built-in API client
Stoplight Elements	Open source	Embeddable React/web components
Mintlify	Hosted, paid	Docs-as-code site with OpenAPI reference pages
ReadMe	Hosted, paid	Developer hub with API logs and metrics

All of them read an OpenAPI file, so writing the spec well matters more than which renderer you choose. For testing the endpoints you document, see the best REST clients and DevHunt's API tools.

A list of REST API methods

If you searched "list of REST API" for the methods themselves: GET (read), POST (create or run an action), PUT (replace), PATCH (partial update), DELETE (remove), plus HEAD and OPTIONS for metadata. If you want a list of public REST APIs to build with, DevHunt maintains a directory of free APIs grouped by category.

FAQ

What is REST API documentation?

It is the reference and guides that explain how to use a REST API: base URL, authentication, every endpoint with its parameters, request and response bodies, error codes, rate limits and examples. Today it is usually generated from an OpenAPI file and published as an interactive website.

What is the best format for REST API documentation?

An OpenAPI description (YAML or JSON) for the reference, plus Markdown guides for the quickstart and concepts. OpenAPI is the industry standard and works with nearly every docs, testing and code-generation tool.

Is Swagger the same as OpenAPI?

Not anymore. Swagger 2.0 was donated and renamed the OpenAPI Specification in 2016; versions since 3.0 are "OpenAPI". "Swagger" now refers to SmartBear's tools, such as Swagger UI and Swagger Editor, which read OpenAPI files.

Which OpenAPI version should I use in 2026?

3.1 has the widest tool support as of October 2026 and aligns schemas with JSON Schema 2020-12. Use 3.2 if you need its features and your renderer, linter and code generators support it.

How do I write REST API documentation quickly?

Generate the OpenAPI file from your framework, add a description and an example to every operation, lint it with Spectral or Redocly CLI, render it with Swagger UI, Redoc or Scalar, and write one quickstart page by hand.