Writing API Documentation in English: Templates and Examples

API documentation is read by thousands of developers. It is one of the most important pieces of technical writing a developer will produce — and one of the least taught. A poorly documented API frustrates integrators, generates endless support tickets, and drives developers to competitor solutions.

This guide focuses on the English writing conventions for API documentation: the vocabulary, sentence structures, tone, and templates that make docs clear for a global audience.

---

Who Reads API Documentation

Before writing, know your audience:

• Integration developers — building apps that consume your API
• Frontend/mobile developers — using your backend APIs
• DevOps engineers — automating workflows with your API
• Product teams at partner companies — evaluating your API for feasibility

All of them need: what this endpoint does, what to send, what to expect back, and what can go wrong.

---

Core Vocabulary for API Documentation

Term	Meaning
endpoint	A specific URL that the API exposes: GET /users/{id}
resource	The entity the API manages: user, order, product
request	What the client sends to the API
response	What the API returns
payload / body	The data sent in the request body (JSON, XML)
query parameter	A key-value pair in the URL: ?limit=10&offset=0
path parameter	A variable embedded in the URL path: /users/{id}
header	Metadata sent with the request: Authorization, Content-Type
status code	HTTP code in the response: 200 OK, 404 Not Found, 429 Too Many Requests
schema	The structure and types of request/response data
authentication	Proving who you are (API key, Bearer token, OAuth)
rate limiting	Restricting how many requests a client can make in a time period
idempotent	An operation that produces the same result regardless of how many times it is called
pagination	Splitting large result sets across multiple requests
deprecation	Announcing that an endpoint or parameter will be removed in a future version

---

The Standard Endpoint Documentation Template

Every endpoint description should follow this structure:

### [HTTP METHOD] /path/to/endpoint

[One sentence describing what this endpoint does.]

**Authentication:** [Required / Not required — specify type: Bearer token / API key]

**Path Parameters**

| Name  | Type   | Required | Description       |
|-------|--------|----------|-------------------|
| id    | string | Yes      | The user's unique identifier |

**Query Parameters**

| Name   | Type    | Required | Default | Description               |
|--------|---------|----------|---------|---------------------------|
| limit  | integer | No       | 20      | Number of results to return (max: 100) |
| offset | integer | No       | 0       | Number of results to skip for pagination |

**Request Body** (for POST / PUT / PATCH)

[Schema with field name, type, required/optional, description]

**Responses**

| Status | Description            |
|--------|------------------------|
| 200    | Success — returns [resource] object |
| 400    | Bad request — invalid parameter |
| 401    | Unauthorized — missing or invalid token |
| 404    | Not found — [resource] with given ID does not exist |
| 429    | Rate limit exceeded — retry after `Retry-After` seconds |

**Example Request**

\`\`\`bash
curl -X GET "https://api.example.com/v1/users/u_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"
\`\`\`

**Example Response**

\`\`\`json
{
  "id": "u_abc123",
  "email": "alex@example.com",
  "role": "admin",
  "created_at": "2025-01-15T09:30:00Z"
}
\`\`\`

---

Writing Style for API Documentation

Use the Present Tense

API docs describe what the system does right now, not what it will do or did do.

❌ “The endpoint will return a list of users.” ✅ “Returns a list of users.”

❌ “The limit parameter will restrict the number of results.” ✅ “The limit parameter restricts the number of results.”

Start Endpoint Descriptions with a Verb

The first sentence of an endpoint description should begin with a verb in the third-person singular.

❌ Avoid	✅ Prefer
This endpoint is for creating users	Creates a new user account
You can use this to retrieve orders	Returns all orders for the authenticated user
Used to delete a record	Deletes the specified record permanently

Common opening verbs: Returns, Creates, Updates, Deletes, Retrieves, Sends, Validates, Cancels, Lists, Searches, Marks

Required vs. Optional — Make It Explicit

Never leave it ambiguous whether a parameter is required.

❌ “email — the user’s email address” ✅ “email (required) — the user’s email address. Must be a valid email address. Maximum 255 characters.”

Write for the Error, Not Just the Happy Path

Most API docs describe what happens when everything goes right. Excellent docs describe what happens when things go wrong:

• What does a 400 error body look like? Provide an example.
• What causes a 422 vs. a 400?
• What should the developer do to recover from each error?

Example error response documentation:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request body contains invalid fields.",
    "details": [
      {
        "field": "email",
        "issue": "Must be a valid email address"
      },
      {
        "field": "age",
        "issue": "Must be a positive integer"
      }
    ]
  }
}

---

Templates for Common Sections

Authentication Section

## Authentication

All requests to the API require authentication using a Bearer token.

Include your token in the `Authorization` header of every request:

\`\`\`
Authorization: Bearer YOUR_API_TOKEN
\`\`\`

You can find your API token in your [Dashboard → API Settings](#).

**Do not expose your API token in client-side code** — treat it as a secret. If your token is compromised, rotate it immediately from the Dashboard.

Rate Limiting Section

## Rate Limiting

The API enforces rate limits to ensure availability for all users.

| Plan  | Limit             |
|-------|-------------------|
| Free  | 100 requests/min  |
| Pro   | 1,000 requests/min|
| Enterprise | Custom    |

When you exceed the rate limit, the API returns **429 Too Many Requests** with a `Retry-After` header indicating how many seconds to wait before retrying.

\`\`\`
HTTP/1.1 429 Too Many Requests
Retry-After: 30
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1712345678
\`\`\`

Pagination Section

## Pagination

All list endpoints support cursor-based pagination.

| Parameter | Type    | Default | Description                              |
|-----------|---------|---------|------------------------------------------|
| limit     | integer | 20      | Number of results per page. Maximum: 100 |
| cursor    | string  | —       | Cursor from the previous response's `next_cursor` field |

**Response structure:**

\`\`\`json
{
  "data": [...],
  "pagination": {
    "total": 1420,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTAwfQ=="
  }
}
\`\`\`

To fetch the next page, pass the `next_cursor` value as the `cursor` parameter in your next request.

Deprecation Notice

> ⚠️ **Deprecated:** This endpoint is deprecated as of API v2 and will be removed on **June 30, 2026**.
> 
> Please migrate to [POST /v2/users](#post-v2-users) before the sunset date.
> 
> See the [migration guide](#) for step-by-step instructions.

---

Changelog / API Versioning Language

When documenting breaking changes and API versions, use this standard vocabulary:

Change type	English phrasing
New endpoint added	”Added: GET /v2/users/search endpoint”
Parameter added	”Added optional include_archived parameter to GET /users”
Parameter deprecated	”Deprecated: The legacy_id field. Use id instead.”
Breaking change	”Breaking: The response schema for GET /orders has changed. The items field is now an array of objects instead of an array of strings.”
Bug fix	”Fixed: POST /webhook endpoint now correctly returns 201 on creation instead of 200.”
Removed	”Removed: DELETE /v1/users/batch — this endpoint was deprecated in v1.4.”

---

RFC 2119 Modal Verbs

API documentation often uses RFC 2119 keywords, which have specific technical meanings. Using them correctly signals professional documentation:

Keyword	Meaning
MUST	Absolute requirement. If you do not do this, the request will fail.
MUST NOT	Absolutely forbidden.
SHOULD	Strongly recommended, but not required. Valid reasons to ignore it may exist.
SHOULD NOT	Not recommended, but not forbidden.
MAY	Optional — permitted but not required.

Example usage:

• “The Content-Type header MUST be set to application/json.”
• “Clients SHOULD implement exponential backoff when handling 429 responses.”
• “The metadata field MAY contain any valid JSON object.”

---

Common Mistakes in API Documentation

1. Ambiguous parameter descriptions

❌ “sort — the sort order” ✅ “sort — Sort order for results. Accepted values: asc (ascending) or desc (descending). Default: desc.”

2. No example for error responses

Developers most need examples when things go wrong, not when they go right.

3. Outdated examples

If your API changes but the examples are not updated, they become harmful. Keep examples testable — ideally auto-generated from tests.

4. Inconsistent English style

Pick a voice (imperative for instructions, third-person for descriptions) and stick to it across all endpoints.

5. Missing “when to use this”

Especially for similar endpoints (PUT vs. PATCH, offset vs. cursor pagination), explain when each is appropriate.

---

Practice

• API Vocabulary Study Set — 15 core API terms with definitions
• Reading: API Documentation Comprehension — read and answer questions about real API docs
• Writing Exercises — write endpoint descriptions and error messages