API Reference DocumentationLesson 3.2

Writing endpoint documentation with parameters and examples

HTTP method documentation, path parameters, query parameters, request body documentation, JSON schema, parameter constraints, required vs optional fields

Endpoint Documentation

Endpoint documentation must be scannable. Developers already know what an API is — they're looking for a specific parameter name, a type constraint, or whether a field is required. Structure your docs for scanning, not reading.

Parameter Table Format

### GET /api/v1/users/{id}

Retrieve a single user by their unique identifier.

**Path Parameters**

| Parameter | Type   | Required | Description                    |
|-----------|--------|----------|--------------------------------|
| id        | string | Yes      | UUID of the user to retrieve   |

**Query Parameters**

| Parameter | Type    | Required | Default | Description                          |
|-----------|---------|----------|---------|--------------------------------------|
| fields    | string  | No       | all     | Comma-separated fields to return     |
| version   | integer | No       | 1       | Response schema version (1 or 2)     |

Request Body Documentation

**Request Body** (application/json)

```json
{
  "email": "string (required) — valid email format",
  "name": "string (required) — 2–100 characters",
  "role": "string (optional) — one of: admin, editor, viewer (default: viewer)"
}
```

Always Show Constraints

Type alone is not enough. Document: min/max length, allowed values for enums, format requirements for dates and emails, and numeric ranges. Every constraint you omit is a 400 error a developer will hit and have to debug without guidance.