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.

Navigating Nuance: Supporting Non-Native Speakers

Writing effective API documentation is about more than just accurately describing functionality; it’s about communicating clearly with a diverse team. A significant portion of that team may be developing their professional English skills alongside their technical abilities, and this can introduce subtle challenges. It’s crucial to move beyond simply stating what the code does and consider how you explain it in a way that minimizes ambiguity and supports comprehension. This isn’t about dumbing down your writing; it’s about recognizing different levels of linguistic fluency and proactively offering support.

One common issue arises during code reviews. Imagine receiving a comment like, “This doesn’t work.” While seemingly straightforward, it lacks crucial context. A more helpful response – particularly for someone still building their English – would be: “I noticed the process_data() function isn’t returning a value. Could you clarify whether this is intended to return a boolean or an object containing the processed data? The documentation currently states it returns ‘an object’, but I’m unsure if that aligns with the current implementation.” This approach directly addresses the problem while providing specific questions for clarification, framing the issue as a potential mismatch between expectation and reality. Similarly, in Slack conversations when describing a pull request, phrasing like “I’ve implemented the endpoint to handle requests with a status parameter” is clearer than simply stating “Fixed API call.”

Another key consideration is the use of precise terminology. Developers often rely on established technical vocabulary, but even within that realm, nuances can be lost in translation. For example, instead of saying “This improves performance,” which can feel vague, consider “This optimization reduces latency by an average of 15% under peak load conditions.” Quantifiable results paired with clear explanations are always preferable. When drafting PR descriptions, aim for active voice and avoid passive constructions that can obscure responsibility. “The team refactored the authentication module to enhance security” is better than “The authentication module was refactored by the team to enhance security.”

Finally, remember that offering support isn’t just about correcting errors; it’s about fostering a collaborative environment. A simple phrase like, “Would you like me to elaborate on any part of this documentation?” or “Do you have any questions about how this function is intended to be used?” demonstrates empathy and willingness to assist. Creating a culture where asking for clarification is encouraged – rather than perceived as a sign of weakness – significantly improves communication effectiveness across the entire team.