API Reference — Writing Comprehensive Endpoint Documentation

In this tutorial, you will learn about API Reference. We cover key concepts, practical examples, and best practices to help you master this topic.

An API reference is the detailed technical documentation for every endpoint in an API, covering HTTP method, URL, parameters, request/response bodies, error codes, and examples.

What You'll Learn

• Structuring an API reference page
• Writing clear parameter descriptions
• Providing useful code examples

Why It Matters

The API reference is where developers spend most of their time. A well-written reference reduces integration time and support requests.

Reference Page Structure

1. Endpoint summary — One-line description of what the endpoint does
2. HTTP method and URL — Full path with variables
3. Parameters — Path, query, header, cookie parameters
4. Request body — Schema with all fields
5. Response — Status codes, headers, body schema
6. Errors — Possible error codes and their meanings
7. Examples — Request and response in multiple languages

Code Examples

## List Users

Returns a paginated list of users.

### Request

`GET /api/v1/users`

### Query Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page | integer | No | Page number (default: 1) |
| limit | integer | No | Items per page (default: 20, max: 100) |
| role | string | No | Filter by role (admin, editor, viewer) |

### Response

Status: 200 OK

```json
{
  "data": [
    {
      "id": 1,
      "name": "Alice",
      "email": "alice@example.com",
      "role": "admin"
    }
  ],
  "total": 42,
  "page": 1,
  "pageSize": 20
}

Errors

Examples

import requests
response = requests.get(
    "https://api.example.com/v1/users",
    headers={"Authorization": "Bearer token"},
    params={"page": 1, "limit": 20}
)
print(response.json())

## Common Mistakes

### 1. Inconsistent Parameter Descriptions
All parameters should follow the same description style.

### 2. No Error Response Schemas
Show the structure of error responses, not just status codes.

### 3. Examples Only in One Language
Provide examples in at least Python, <a href="/programming-languages/javascript/">JavaScript</a>, and curl.

### 4. Missing Field Constraints
Document min/max lengths, enum values, and formats.

### 5. No Realistic Examples
Use realistic data in examples so developers can relate.

## Practice Questions

1. What sections should every endpoint reference include?
2. Why are multiple language examples important?
3. How detailed should parameter descriptions be?
4. What should error documentation include beyond status codes?
5. How do you document conditional fields?

**Answers:**
1. Summary, URL, parameters, request body, response, errors, examples.
2. Developers work in different languages. Cover the most common ones.
3. Include allowed values, defaults, constraints, and usage notes.
4. Error response body structure, possible values, and recovery steps.
5. Note which conditions make a field required or optional.

**Challenge:** Write a complete API reference page for a payment endpoint that accepts payment amount, currency, source token, and returns a payment ID and status.

## FAQ

<details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">Should the API reference be auto-generated?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>: Yes, from OpenAPI specs. Manual updates are error-prone and often outdated.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">How do I handle deprecated endpoints in the reference?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>: Mark them with a deprecated notice and link to the replacement.</p>
</div></details><details style="margin-bottom:12px;border:1px solid #e2e8f0;border-radius:10px;overflow:hidden"><summary style="cursor:pointer;padding:14px 18px;font-weight:600;font-size:1.05rem;background:#f8fafc;border-bottom:1px solid #e2e8f0;color:#1e293b">What is the ideal length for an endpoint description?</summary><div style="padding:14px 18px;color:#475569;line-height:1.7;background:#fff"><p>: 1-3 sentences explaining what it does and when to use it.</p>
</div></details>