api-documentation

API Documentation Skill

Standards for documenting REST and GraphQL APIs.

REST API Documentation

Endpoint Format

## Endpoint Name

Brief description of what this endpoint does.

**Method:** `GET` | `POST` | `PUT` | `PATCH` | `DELETE`
**Path:** `/api/v1/resource/:id`
**Auth:** Bearer token | API key | None

### Path Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| id | string | Resource ID |

### Query Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| page | integer | No | 1 | Page number |
| limit | integer | No | 20 | Items per page |
| sort | string | No | -createdAt | Sort field |

### Request Body

\`\`\`json
{
  "field1": "value",
  "field2": 123
}
\`\`\`

### Response

**Success (200 OK)**

\`\`\`json
{
  "data": { ... },
  "meta": { ... }
}
\`\`\`

**Errors**

| Status | Code | Description |
|--------|------|-------------|
| 400 | VALIDATION_ERROR | Invalid input |
| 404 | NOT_FOUND | Resource not found |

Authentication Section

# Authentication

All API requests require authentication via one of:

## Bearer Token (Recommended)

\`\`\`bash
curl -H "Authorization: Bearer <token>" https://api.example.com/v1/users
\`\`\`

Tokens expire after 1 hour. Use the refresh token to obtain a new access token.

## API Key

\`\`\`bash
curl -H "X-API-Key: <api-key>" https://api.example.com/v1/users
\`\`\`

API keys don't expire but can be revoked in the dashboard.

## OAuth 2.0

For third-party integrations:

1. Redirect to `/oauth/authorize`
2. User grants permission
3. Receive authorization code
4. Exchange code for tokens

Pagination Documentation

# Pagination

List endpoints return paginated results.

## Request Parameters

| Parameter | Type | Default | Max | Description |
|-----------|------|---------|-----|-------------|
| page | integer | 1 | - | Page number (1-indexed) |
| limit | integer | 20 | 100 | Items per page |

## Response Format

\`\`\`json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
  }
}
\`\`\`

## Cursor-Based Pagination

For large datasets, use cursor pagination:

\`\`\`bash
GET /api/v1/events?cursor=abc123&limit=50
\`\`\`

\`\`\`json
{
  "data": [...],
  "cursors": {
    "next": "def456",
    "prev": null
  }
}
\`\`\`

Error Documentation

# Error Handling

## Error Response Format

All errors return a consistent JSON structure:

\`\`\`json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ],
    "requestId": "req_abc123"
  }
}
\`\`\`

## Error Codes

### Client Errors (4xx)

| Code | Status | Description | Resolution |
|------|--------|-------------|------------|
| VALIDATION_ERROR | 400 | Invalid input | Check request body |
| UNAUTHORIZED | 401 | No valid credentials | Include auth header |
| FORBIDDEN | 403 | Insufficient permissions | Request access |
| NOT_FOUND | 404 | Resource doesn't exist | Check resource ID |
| CONFLICT | 409 | Resource already exists | Use different values |
| RATE_LIMITED | 429 | Too many requests | Wait and retry |

### Server Errors (5xx)

| Code | Status | Description | Resolution |
|------|--------|-------------|------------|
| INTERNAL_ERROR | 500 | Server error | Contact support |
| SERVICE_UNAVAILABLE | 503 | Maintenance | Retry later |

GraphQL Documentation

Schema Documentation

# GraphQL Schema

## Types

### User

\`\`\`graphql
type User {
  """Unique identifier"""
  id: ID!

  """User's email address"""
  email: String!

  """Display name"""
  name: String

  """Account creation timestamp"""
  createdAt: DateTime!

  """User's orders"""
  orders(first: Int, after: String): OrderConnection!
}
\`\`\`

### Input Types

\`\`\`graphql
input CreateUserInput {
  email: String!
  name: String
  role: UserRole = USER
}
\`\`\`

Query Documentation

## Queries

### user

Fetch a single user by ID.

\`\`\`graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    email
    name
    createdAt
  }
}
\`\`\`

**Arguments:**

| Argument | Type | Required | Description |
|----------|------|----------|-------------|
| id | ID | Yes | User ID |

**Example:**

\`\`\`json
{
  "id": "usr_123"
}
\`\`\`

**Response:**

\`\`\`json
{
  "data": {
    "user": {
      "id": "usr_123",
      "email": "[email protected]",
      "name": "John Doe",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}
\`\`\`

Mutation Documentation

## Mutations

### createUser

Create a new user account.

\`\`\`graphql
mutation CreateUser($input: CreateUserInput!) {
  createUser(input: $input) {
    user {
      id
      email
    }
    errors {
      field
      message
    }
  }
}
\`\`\`

**Input:**

\`\`\`json
{
  "input": {
    "email": "[email protected]",
    "name": "Jane Smith"
  }
}
\`\`\`

**Success Response:**

\`\`\`json
{
  "data": {
    "createUser": {
      "user": {
        "id": "usr_456",
        "email": "[email protected]"
      },
      "errors": null
    }
  }
}
\`\`\`

**Error Response:**

\`\`\`json
{
  "data": {
    "createUser": {
      "user": null,
      "errors": [
        {
          "field": "email",
          "message": "Email already exists"
        }
      ]
    }
  }
}
\`\`\`

SDK Examples

Language-Specific Examples

## SDK Examples

### JavaScript/TypeScript

\`\`\`typescript
import { Client } from '@api/sdk'

const client = new Client({ apiKey: 'your-key' })

// List users
const users = await client.users.list({ limit: 10 })

// Create user
const user = await client.users.create({
  email: '[email protected]',
  name: 'John Doe'
})
\`\`\`

### Python

\`\`\`python
from api_sdk import Client

client = Client(api_key='your-key')

# List users
users = client.users.list(limit=10)

# Create user
user = client.users.create(
    email='[email protected]',
    name='John Doe'
)
\`\`\`

### cURL

\`\`\`bash
# List users
curl -X GET "https://api.example.com/v1/users?limit=10" \
  -H "Authorization: Bearer $API_KEY"

# Create user
curl -X POST "https://api.example.com/v1/users" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","name":"John Doe"}'
\`\`\`

Integration

Used by:

• api-doc-writer agent