# Prompt: Update API Documentation

Use this prompt template when you need to update API documentation after code changes.

## Context

**Project:** [PROJECT_NAME]
**File(s) changed:** [LIST_OF_API_FILES]
**API documentation location:** [DOCS_PATH] (typically `docs/api.md` or `docs/api/`)

## Goal

Update API documentation to reflect changes in:
- New endpoints/routes
- Modified request/response formats
- Changed parameters or headers
- Updated authentication requirements
- New or modified error codes
- Breaking changes to existing APIs

## Current State

### Changed API Code

```[LANGUAGE]
[PASTE_CHANGED_API_CODE_HERE]
```

### Current API Documentation

```markdown
[PASTE_CURRENT_API_DOCS_HERE]
```

## Requirements

**What to update:**

- [ ] Endpoint URLs and HTTP methods
- [ ] Request parameters (query, path, body)
- [ ] Request headers and authentication
- [ ] Request body schema/format
- [ ] Response status codes
- [ ] Response body schema/format
- [ ] Error responses and codes
- [ ] Example requests and responses
- [ ] Rate limiting information (if changed)
- [ ] Deprecation notices (if applicable)
- [ ] Migration guide (for breaking changes)

**Documentation format:**

Follow the project's API documentation style. Common formats include:

**OpenAPI/Swagger:**
```yaml
/users/{id}:
  get:
    summary: Get user by ID
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
    responses:
      200:
        description: User found
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
```

**Markdown (REST):**
```markdown
### GET /users/{id}

Get user by ID.

**Parameters:**
- `id` (path, required): User ID as integer

**Response (200 OK):**
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}
```
**Errors:**
- `404 Not Found`: User not found
- `401 Unauthorized`: Authentication required
```

**GraphQL:**
```markdown
### Query: user

Fetch a single user by ID.

**Arguments:**
- `id: ID!` - User ID (required)

**Returns:** `User`

**Example:**
```graphql
query {
  user(id: "123") {
    id
    name
    email
  }
}
```
```

## Output Format

Provide the updated API documentation in the project's standard format. Include:

1. **Summary of changes** (brief changelog)
2. **Updated documentation** (complete section, ready to copy-paste)
3. **Breaking changes** (if any, with migration guide)
4. **Example usage** (cURL, HTTP, or client library examples)

## Examples

### Example 1: New Endpoint

**Code change:**
```python
@app.post("/api/users")
async def create_user(user: UserCreate) -> User:
    """Create a new user."""
    return await user_service.create(user)
```

**Updated docs:**
```markdown
### POST /api/users

Create a new user.

**Request Body:**
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "secret123"
}
```

**Response (201 Created):**
```json
{
  "id": 456,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2025-01-07T12:00:00Z"
}
```

**Errors:**
- `400 Bad Request`: Invalid input (e.g., email already exists)
- `422 Unprocessable Entity`: Validation error

**Example (cURL):**
```bash
curl -X POST https://api.example.com/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John Doe","email":"john@example.com","password":"secret123"}'
```
```

### Example 2: Modified Response Format (Breaking Change)

**Code change:**
```python
# Old response: {"id": 123, "full_name": "John Doe"}
# New response: {"id": 123, "first_name": "John", "last_name": "Doe"}
```

**Updated docs:**
```markdown
### GET /api/users/{id}

Get user by ID.

**BREAKING CHANGE (v2.0):** Response format changed from v1.x

**Migration Guide:**
- `full_name` field removed
- Replaced with `first_name` and `last_name` fields
- Update clients to parse new format: `${first_name} ${last_name}`

**Response (200 OK) - v2.0:**
```json
{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com"
}
```

**Old Response (200 OK) - v1.x (deprecated):**
```json
{
  "id": 123,
  "full_name": "John Doe",
  "email": "john@example.com"
}
```

**Deprecation:** v1 format will be removed in v3.0 (estimated: June 2025)
```

### Example 3: New Query Parameters

**Code change:**
```python
@app.get("/api/users")
async def list_users(
    limit: int = 10,
    offset: int = 0,
    sort_by: str = "created_at",  # NEW
    order: str = "desc"           # NEW
) -> list[User]:
    """List users with pagination and sorting."""
    ...
```

**Updated docs:**
```markdown
### GET /api/users

List users with pagination and sorting.

**Query Parameters:**
- `limit` (optional, default: 10): Maximum number of results (1-100)
- `offset` (optional, default: 0): Number of results to skip
- `sort_by` (optional, default: "created_at"): Field to sort by
  - Allowed values: `created_at`, `name`, `email`
- `order` (optional, default: "desc"): Sort order
  - Allowed values: `asc`, `desc`

**Response (200 OK):**
```json
{
  "total": 1234,
  "limit": 10,
  "offset": 0,
  "users": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
  ]
}
```

**Example:**
```bash
# Get 20 users, sorted by name ascending
curl "https://api.example.com/api/users?limit=20&sort_by=name&order=asc"
```
```

## Task

Please update the API documentation based on the code changes provided above. Ensure:

1. All endpoint changes are documented
2. Request/response examples are accurate
3. Breaking changes are clearly marked
4. Migration guides are provided for breaking changes
5. Examples use realistic data
6. Error responses are comprehensive

## Related Prompts

- **README updates**: `prompts/documentation/update-readme.md`
- **Docstrings**: `prompts/documentation/add-docstrings.md`
- **Code comments**: `prompts/documentation/write-code-comments.md`
- **PR description**: `prompts/documentation/write-pr-description.md`

## Related Documentation

- **Playbook**: `playbooks/updating-documentation.md`
- **Knowledge base**: `.claude/knowledge/documentation/keeping-docs-updated.md`
- **Engineering standards**: `.claude/standards/ENGINEERING_STANDARDS.md#api-documentation`
- **Rule #11**: `.claude/standards/CLAUDE_CODE_RULES.md#11-documentation-updates`
