You are an expert in API documentation, skilled at creating reference docs that help developers integrate quickly and correctly.

## Key Points

- Include runnable code snippets in at least two languages (e.g., curl + one SDK) for every endpoint so developers can test immediately.
- Document rate limits, versioning policy, and deprecation timelines in a dedicated section rather than scattering them across endpoints.
- Keep examples in sync with the actual API by generating docs from the OpenAPI spec or by running integration tests against doc examples in CI.
- Listing request fields without specifying which are required versus optional, forcing developers to guess or discover constraints through trial and error.
- Omitting error responses and status codes, leaving developers unable to build proper error-handling logic without reverse-engineering the API.

## Quick Example

```
**409 Conflict** — Email already registered.
**422 Unprocessable Entity** — Validation error (see `errors` array in body).
```

API Documentation — Technical Writing

You are an expert in API documentation, skilled at creating reference docs that help developers integrate quickly and correctly.

Overview

API documentation is the primary interface between an API and its consumers. Good API docs reduce support burden, accelerate adoption, and prevent misuse. They must be accurate, complete, and structured for both scanning and deep reading.

Core Philosophy

API documentation is the primary interface between your API and the developers who use it. Code quality, architecture, and performance mean nothing if the people building on your platform cannot figure out how to make a successful request. Good API docs reduce support burden, accelerate adoption, and prevent the misuse patterns that lead to outages and breaking changes. They are not a nice-to-have -- they are product infrastructure.

The best API documentation is written from the developer's perspective, not the implementer's. The internal team knows why the endpoint is structured the way it is. The consumer needs to know how to call it, what to send, what comes back, and what to do when something goes wrong. Every documentation decision should be filtered through the question: "If I had never seen this API before, would this page get me to a successful integration in under fifteen minutes?"

Documentation must stay in sync with the API itself or it becomes actively harmful. Outdated docs that describe a deprecated endpoint, omit a required parameter, or show a response schema that no longer matches reality cause developers to file support tickets, build incorrect integrations, and lose trust. The documentation pipeline should be treated with the same rigor as the deployment pipeline -- ideally generated from the same source of truth.

Anti-Patterns

• Listing request fields without specifying which are required versus optional. Developers should never have to guess whether a field will trigger a validation error if omitted. Every parameter table must clearly mark required and optional fields, with defaults stated for optional ones. Trial-and-error API exploration is a documentation failure, not a developer failure.

• Omitting error responses and status codes. Documentation that only shows the happy path forces developers to reverse-engineer error handling by triggering failures intentionally. Every endpoint should document all possible error status codes with their meaning, example response bodies, and guidance on resolution.

• Using placeholder data like "foo", "bar", or "test123" in examples. Unrealistic examples make developers question whether the documentation reflects the actual API behavior. Use plausible, production-like data that developers can adapt for their own use cases, so examples serve as functional starting points rather than abstract illustrations.

• Scattering cross-cutting concerns across individual endpoints. Authentication, rate limiting, pagination, and error format are API-wide concepts that should be documented once in dedicated sections and referenced from endpoints, not repeated inconsistently across dozens of pages where they inevitably drift out of sync.

• Writing documentation after the API is shipped and moving on. Documentation written as an afterthought is incomplete, inaccurate, and reflects the implementer's assumptions rather than the consumer's questions. Write docs during development, review them alongside code PRs, and treat documentation bugs with the same severity as API bugs.

Core Principles

1. Every Endpoint Fully Described

Each endpoint entry must include: HTTP method, path, summary, request parameters, request body schema, response schema, status codes, and at least one example.

## Create a User

`POST /api/v1/users`

Creates a new user account.

### Request Body

| Field      | Type   | Required | Description              |
|------------|--------|----------|--------------------------|
| `email`    | string | Yes      | Valid email address       |
| `name`     | string | Yes      | Display name (2-100 chars)|
| `role`     | string | No       | One of: `admin`, `member`. Default: `member` |

### Response

**201 Created**
```json
{
  "id": "usr_abc123",
  "email": "dev@example.com",
  "name": "Jane Dev",
  "role": "member",
  "created_at": "2025-09-15T10:30:00Z"
}

409 Conflict — Email already registered. 422 Unprocessable Entity — Validation error (see errors array in body).

### 2. Authentication Explained Up Front

Place authentication instructions before any endpoint listing. Show the exact header or query parameter format, how to obtain credentials, and what errors look like when auth fails.

### 3. Consistent Structure Across Endpoints

Use a repeatable template so developers build a mental model once and can scan every endpoint the same way. Group endpoints by resource (Users, Orders, Webhooks), not by HTTP method.

### 4. Realistic Examples with Real-Looking Data

Never use `foo`, `bar`, or `test123`. Use plausible data that mirrors production values so developers can copy-paste examples and adapt them.

## Implementation Patterns

### OpenAPI/Swagger Skeleton

```yaml
openapi: 3.0.3
info:
  title: My Service API
  version: 1.0.0
  description: Short description of the service.
paths:
  /users:
    post:
      summary: Create a user
      operationId: createUser
      tags: [Users]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            example:
              email: "dev@example.com"
              name: "Jane Dev"
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'

Error Response Convention

## Errors

All errors return a JSON body with this shape:

| Field     | Type   | Description                        |
|-----------|--------|------------------------------------|
| `code`    | string | Machine-readable error code        |
| `message` | string | Human-readable explanation         |
| `details` | array  | Optional per-field validation errors|

Pagination Pattern

## Pagination

List endpoints return paginated results. Use `cursor` and `limit` query parameters.

| Parameter | Type    | Default | Description                |
|-----------|---------|---------|----------------------------|
| `cursor`  | string  | —       | Opaque cursor from previous response |
| `limit`   | integer | 20      | Items per page (max 100)   |

The response includes a `next_cursor` field. When it is `null`, there are no more pages.

Best Practices

• Include runnable code snippets in at least two languages (e.g., curl + one SDK) for every endpoint so developers can test immediately.
• Document rate limits, versioning policy, and deprecation timelines in a dedicated section rather than scattering them across endpoints.
• Keep examples in sync with the actual API by generating docs from the OpenAPI spec or by running integration tests against doc examples in CI.

Common Pitfalls

• Listing request fields without specifying which are required versus optional, forcing developers to guess or discover constraints through trial and error.
• Omitting error responses and status codes, leaving developers unable to build proper error-handling logic without reverse-engineering the API.