Claude-Code-Workflow/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt

# API-Level Documentation Template

Generate comprehensive API documentation following this structure:

## Overview
[Brief description of the API's purpose and capabilities]

## Authentication
### Authentication Method
[e.g., JWT, OAuth2, API Keys]

### Obtaining Credentials
```bash
# Example authentication flow
```

### Using Credentials
```http
GET /api/resource HTTP/1.1
Authorization: Bearer <token>
```

---

## Base URL
```
Production: https://api.example.com/v1
Staging: https://staging.api.example.com/v1
```

## Common Response Codes
| Code | Description |
|------|-------------|
| 200  | Success |
| 201  | Created |
| 400  | Bad Request |
| 401  | Unauthorized |
| 403  | Forbidden |
| 404  | Not Found |
| 500  | Internal Server Error |

---

## Endpoints

### Resource: Users

#### GET /users
**Description**: Retrieves a paginated list of users.

**Query Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `limit` | number | No | Number of results (default: 20, max: 100) |
| `offset` | number | No | Pagination offset (default: 0) |
| `sort` | string | No | Sort field (e.g., `name`, `-created_at`) |

**Example Request**:
```http
GET /users?limit=10&offset=0&sort=-created_at HTTP/1.1
Authorization: Bearer <token>
```

**Response (200 OK)**:
```json
{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 100,
    "limit": 10,
    "offset": 0
  }
}
```

**Error Response (401 Unauthorized)**:
```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}
```

---

#### GET /users/:id
**Description**: Retrieves a single user by ID.

**Path Parameters**:
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | number | User ID |

**Example Request**:
```http
GET /users/123 HTTP/1.1
Authorization: Bearer <token>
```

**Response (200 OK)**:
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

---

#### POST /users
**Description**: Creates a new user.

**Request Body**:
```json
{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "password": "securePassword123"
}
```

**Validation Rules**:
- `name`: Required, 2-100 characters
- `email`: Required, valid email format, must be unique
- `password`: Required, minimum 8 characters

**Response (201 Created)**:
```json
{
  "id": 124,
  "name": "Jane Smith",
  "email": "jane@example.com",
  "created_at": "2024-01-20T12:00:00Z"
}
```

**Error Response (400 Bad Request)**:
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "email",
        "message": "Email already exists"
      }
    ]
  }
}
```

---

#### PUT /users/:id
**Description**: Updates an existing user.

**Path Parameters**:
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | number | User ID |

**Request Body** (all fields optional):
```json
{
  "name": "Jane Doe",
  "email": "jane.doe@example.com"
}
```

**Response (200 OK)**:
```json
{
  "id": 124,
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "updated_at": "2024-01-21T09:15:00Z"
}
```

---

#### DELETE /users/:id
**Description**: Deletes a user.

**Path Parameters**:
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | number | User ID |

**Response (204 No Content)**:
[Empty response body]

---

## Rate Limiting
- **Limit**: 1000 requests per hour per API key
- **Headers**:
  - `X-RateLimit-Limit`: Total requests allowed
  - `X-RateLimit-Remaining`: Requests remaining
  - `X-RateLimit-Reset`: Unix timestamp when limit resets

---

## SDKs and Client Libraries
- [JavaScript/TypeScript SDK](./sdks/javascript.md)
- [Python SDK](./sdks/python.md)

---

## Webhooks
[Description of webhook system if applicable]

---

## Changelog
### v1.1.0 (2024-01-20)
- Added user sorting functionality
- Improved error messages

### v1.0.0 (2024-01-01)
- Initial API release

---

**API Version**: 1.1.0
**Last Updated**: [Auto-generated timestamp]
**Support**: api-support@example.com