API Documentation

Good API documentation is the difference between a developer integrating your API in 20 minutes versus spending two days in Slack asking questions. The goal is to answer every common question before it’s asked.

Endpoint reference structure

For each endpoint, document in this order:

1. What it does — one sentence, no jargon
2. Authentication — what credentials are needed
3. Request — method, path, parameters, body schema
4. Response — success shape, status codes, error shapes
5. Examples — curl request + JSON response

## POST /api/v1/users

Create a new user account.

**Authentication:** Bearer token required.

**Request body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | yes | Valid email address |
| name | string | yes | Full name |
| role | string | no | "admin" or "member" (default: "member") |

**Response:** `201 Created`
```json
{
  "id": "usr_abc123",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "role": "member",
  "createdAt": "2025-01-15T09:30:00Z"
}

Errors:

Status	Code	When
400	invalid_email	Email format is invalid
409	duplicate_email	Email already registered
422	missing_field	Required field not provided

## Request examples

Always include a curl example that actually works:

```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "name": "Jane Doe"}'

Show the actual values, not placeholders like <your-api-key>. Use environment variables for secrets: $API_KEY.

Error documentation

Document every error code your API returns. Developers need to know:

• What status code to expect
• What error code string to check for
• What it means and how to fix it
• Whether it’s retryable

Don’t return generic “Bad request” — a specific error code saves hours of debugging.

Authentication guide

Write a separate authentication overview that covers:

1. How to get API keys
2. Where to put them (header vs query param)
3. What happens when they expire
4. Rate limits and what happens when exceeded
5. How to rotate keys without downtime

See references/api-doc-template.md for a complete template.

When it triggers

• documenting an API endpoint
• writing API reference docs
• adding authentication documentation
• describing error responses