Professional English for API Documentation: Style, Register, and Structure

API documentation is some of the most read, most copied, and most quickly judged writing in the software industry. A developer evaluating your API will often decide within minutes whether to continue based on how clear and professional your docs are. Good API documentation requires not just technical accuracy but a specific kind of English: precise, consistent, and free of ambiguity. This guide covers the key decisions that determine whether your docs feel professional or amateurish.

---

Reference Docs vs Guides: Different Registers

API documentation comes in two primary forms, and they require different writing styles.

Reference Documentation

Reference docs describe exactly what each endpoint, parameter, method, or type does. The reader already knows what they want to achieve — they are looking up the specific detail. The register should be:

• Terse and precise — no unnecessary words
• Third person, present tense — “Returns an array of User objects”
• Consistent — use the same phrasing pattern for every endpoint
• Scannable — heavy use of tables, code examples, and labelled sections

Guides (How-to Docs and Tutorials)

Guides walk the developer through a task or concept. The register is slightly warmer and more explanatory:

• Second person, present tense — “To authenticate, send a POST request to…”
• More prose and context — explain why, not just what
• Progressive — build from simple to complex

A common mistake is mixing registers — writing guide-style explanatory prose in the middle of a reference endpoint description, or writing terse reference-style bullets in a guide where context is needed.

---

Verb Tense: The Present Tense Rule

API reference documentation uses the simple present tense throughout. This is a strong convention and deviating from it sounds immediately off.

Correct:

• “Returns an array of all active subscriptions.”
• “Accepts a JSON request body.”
• “Raises a ValidationError if the email field is missing.”
• “Throws a 404 Not Found error if the resource does not exist.”

Incorrect:

• “Will return an array…” (future tense — avoid in reference docs)
• “Returned an array…” (past tense — obviously wrong)
• “Should return…” (hedging — avoid, unless you specifically mean the spec, not the implementation)

The present tense convention treats the API as a fact of the world: it does this. It is not something that will do or might do.

---

Writing Parameter Descriptions

Parameter descriptions are one of the hardest things to write consistently. Here is a structure that works:

{name} (type, required|optional): Description. Default: {value}.

Examples

user_id (string, required): The unique identifier of the user. Must match the
authenticated user's ID or belong to an organisation the authenticated user
manages.

page (integer, optional): The page number for paginated results. Defaults to 1.
Minimum: 1.

include_archived (boolean, optional): When true, includes archived records in
the response. Defaults to false.

created_after (ISO 8601 datetime, optional): Returns only records created after
this timestamp. Example: 2026-01-15T09:00:00Z.

Key Rules for Parameter Descriptions

• Start with a capital letter, end with a period. Consistency matters.
• State the required/optional status — do not make the developer infer it.
• Specify the default value for optional parameters — always.
• Include constraints — min/max, format, allowed values. If there are allowed values, list them: “One of active, inactive, pending.”
• Give a format example for non-obvious types (dates, identifiers, patterns).

---

Returns, Throws, Raises: The Standard Verbs

Three verbs dominate API reference documentation for describing responses:

Verb	Use Case	Example
Returns	Describes the successful response body	”Returns a Payment object on success.”
Throws	Used in typed languages (Java, TypeScript) for exceptions	”Throws an AuthenticationException if the token is invalid.”
Raises	Used in Python documentation for exceptions	”Raises a ValueError if amount is negative.”
Responds with	HTTP-level description	”Responds with 200 OK and the updated resource.”

Choose one convention and be consistent within a codebase or docs set. Mixing “throws” and “raises” in the same documentation is a red flag for inconsistency.

---

A Full Endpoint Documentation Example

The following is an example of a well-structured endpoint document for a fictional REST API:

POST /v1/payments

Creates a new payment and returns the payment record. The payment is
processed asynchronously; the initial status is always `pending`.

Authentication: Bearer token required.

Request Body (application/json)

  amount        (integer, required):  The payment amount in the smallest
                                      currency unit (e.g., pence for GBP).
                                      Minimum: 1.

  currency      (string, required):   ISO 4217 currency code. One of:
                                      "GBP", "USD", "EUR".

  recipient_id  (string, required):   The ID of the recipient account.

  reference     (string, optional):   A client-defined reference string,
                                      returned unchanged in the response.
                                      Maximum 64 characters.

  idempotency_key (string, optional): A unique key to safely retry requests.
                                      If a payment with this key already
                                      exists, returns the original payment
                                      rather than creating a new one.

Returns

  201 Created — A Payment object:

    {
      "id": "pay_01J2K3L4M5",
      "status": "pending",
      "amount": 5000,
      "currency": "GBP",
      "recipient_id": "acc_9XY7Z",
      "reference": "invoice-2026-001",
      "created_at": "2026-06-15T10:00:00Z"
    }

Errors

  400 Bad Request    — Missing or invalid request parameters.
  401 Unauthorized   — Missing or invalid authentication token.
  404 Not Found      — The specified recipient_id does not exist.
  409 Conflict       — A payment with the given idempotency_key
                       already exists (returns the existing payment).
  422 Unprocessable  — Payment could not be processed (e.g., insufficient
                       funds in the source account).

---

Writing Consistent Prose in Guides

When writing guides rather than reference docs, a few additional English conventions apply:

• Use “you” to address the developer directly: “Before you can call the API, you need to obtain an API key.”
• Use imperatives for steps: “Send a POST request to /v1/auth/token. Include the client_id and client_secret in the request body.”
• Explain prerequisites upfront: “This guide assumes you have already completed the authentication setup.”
• Use transition phrases to link steps: “Once you have the token, you can use it to authenticate all subsequent requests.”
• Note edge cases explicitly: “If the user does not exist, the endpoint returns a 404. Handle this case before proceeding.”

---

Key Takeaways

• Use present tense throughout reference documentation — “Returns”, not “will return”.
• Distinguish reference docs (terse, third person, scannable) from guides (explanatory, second person, progressive).
• Parameter descriptions should always state type, required/optional, default, constraints, and format examples.
• Use Returns / Throws / Raises consistently — pick one convention per project and stick to it.
• A well-structured endpoint doc includes: description, authentication, request body parameters, success response, and error table.