How to Write API Documentation in English

Good API documentation is one of the most valuable things an engineering team can produce. It determines whether developers can use your API successfully — or give up and look elsewhere. Writing clear API docs in English requires specific patterns, vocabulary, and conventions that experienced technical writers use consistently.

---

The Structure of an API Reference Entry

Every endpoint in an API reference should include:

1. Title and HTTP method + path
2. Short description (one sentence)
3. Authentication requirements
4. Request parameters (path, query, body)
5. Request example
6. Response schema
7. Response example
8. Error codes

---

Language Patterns for Endpoint Descriptions

The standard convention is to describe what an endpoint does, using a verb in the third person present:

“Returns a list of all users in the organisation.”

“Creates a new order and returns the order ID.”

“Deletes the specified webhook and cancels future deliveries.”

“Updates one or more fields of the user profile.”

“Retrieves a paginated list of transactions filtered by date range.”

Do not write:

• “You can use this endpoint to get users.” — too informal
• “This will return users.” — imprecise tense
• “Get users.” — too minimal

---

Describing Parameters

Path parameters:

“userId — string, required. The unique identifier of the user. Example: usr_a1b2c3.”

Query parameters:

“page — integer, optional. The page number for paginated results. Default: 1. Minimum: 1.”

“limit — integer, optional. The number of results per page. Default: 20. Maximum: 100.”

Request body fields:

“email — string, required. The user’s email address. Must be a valid email format.”

“role — enum, required. The user’s permission level. Accepted values: admin, member, viewer.”

---

Writing Request and Response Examples

Use realistic, self-explanatory examples. Avoid foo, bar, test123:

Request example:

POST /v1/users
Authorization: Bearer sk_live_abc123
Content-Type: application/json

{
  "email": "alice@example.com",
  "role": "member",
  "name": "Alice Chen"
}

Response example:

{
  "id": "usr_a1b2c3",
  "email": "alice@example.com",
  "role": "member",
  "name": "Alice Chen",
  "createdAt": "2026-06-13T09:00:00Z"
}

---

Writing Error Messages

Good error messages in an API have three qualities: they tell you what went wrong, why it went wrong, and ideally what to do about it.

Weak error message	Strong error message
”Bad request."	"The email field is required and must be a valid email address."
"Not found."	"No user with the ID usr_xyz was found. Verify the ID and try again."
"Server error."	"An unexpected error occurred. Please retry the request. If the issue persists, contact support with reference ID: ERR-20260613-8842."
"Unauthorised."	"The provided API key is invalid or has been revoked. Check your key in the dashboard.”

---

Language for Notes, Warnings, and Tips

Use callout blocks to highlight important information:

Notes — supplementary information:

“Note: This endpoint returns results in descending order by creation date. Pagination is applied before filtering.”

Warnings — actions that could cause problems:

“Warning: Deleting a user is permanent and cannot be undone. All associated data will be removed.”

Deprecation notices:

“Deprecated: The name field is deprecated as of API v2.1. Use firstName and lastName instead. The name field will be removed in v3.0.”

---

Writing the Authentication Section

“All API requests must include a valid API key in the Authorization header using the Bearer token scheme.”

“API keys are scoped to a specific set of permissions. Attempting to perform an action outside your key’s permissions will return a 403 Forbidden response.”

“Do not include your API key in URLs or log it to files. Treat it as a password.”

---

Common Documentation Language Patterns

Pattern	Example
”Returns X"	"Returns a paginated list of invoices."
"Creates X and returns Y"	"Creates the order and returns the full order object."
"Must be X"	"The value must be a valid ISO 8601 date string."
"If X, then Y"	"If the request body is omitted, the endpoint returns the current configuration."
"Defaults to X"	"Defaults to false if not provided."
"See also"	"See also: Webhook Events for a list of event types.”

---

Quick Self-Editing Checklist

Before publishing API documentation, verify:

• Every endpoint has a description, parameters, and at least one example
• Examples use realistic values, not placeholders like “string” or “value”
• Error codes are documented with explanations
• Deprecated fields are clearly marked
• Language is consistent — do not mix “returns” and “will return” for the same type of endpoint

---

Clear API documentation is a product, not an afterthought. The developers who use your API will spend more time reading your docs than talking to you. Write for the reader who is stuck at midnight trying to make your endpoint work.