# Unified API Documentation Template

Generate comprehensive API documentation. This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.

---

## Part A: Code API (For Libraries, Modules, SDKs)

**Use this section when documenting**: Exported functions, classes, interfaces, and types from code modules.

**Omit this section if**: This is a pure web service with only HTTP endpoints and no programmatic API.

### 1. Exported Functions

For each exported function, provide:
```typescript
/**
 * Brief one-line description of what the function does
 * @param paramName - Parameter type and description
 * @returns Return type and description
 * @throws ErrorType - When this error occurs
 */
export function functionName(paramName: ParamType): ReturnType;
```

**Example**:
```typescript
/**
 * Authenticates a user with email and password
 * @param credentials - User email and password
 * @returns Authentication token and user info
 * @throws AuthenticationError - When credentials are invalid
 */
export function authenticate(credentials: Credentials): Promise<AuthResult>;
```

### 2. Exported Classes

For each exported class, provide:
```typescript
/**
 * Brief one-line description of the class purpose
 */
export class ClassName {
  constructor(param: Type);

  // Public properties
  propertyName: Type;

  // Public methods
  methodName(param: Type): ReturnType;
}
```

**Example**:
```typescript
/**
 * Manages user session lifecycle and token refresh
 */
export class SessionManager {
  constructor(config: SessionConfig);

  // Current session state
  isActive: boolean;

  // Refresh the session token
  refresh(): Promise<void>;

  // Terminate the session
  destroy(): void;
}
```

### 3. Exported Interfaces

For each exported interface, provide:
```typescript
/**
 * Brief description of what this interface represents
 */
export interface InterfaceName {
  field1: Type;  // Field description
  field2: Type;  // Field description
  method?: (param: Type) => ReturnType;  // Optional method
}
```

### 4. Type Definitions

For each exported type, provide:
```typescript
/**
 * Brief description of what this type represents
 */
export type TypeName = string | number | CustomType;
```

---

## Part B: HTTP API (For Web Services, REST APIs, GraphQL)

**Use this section when documenting**: HTTP endpoints, REST APIs, GraphQL APIs, webhooks.

**Omit this section if**: This is a library/SDK with no HTTP interface.

### 1. Overview

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

**Base URL**:
```
Production: https://api.example.com/v1
Staging: https://staging.api.example.com/v1
Development: http://localhost:3000/api/v1
```

### 2. Authentication

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

#### Obtaining Credentials
```bash
# Example: Login to get token
curl -X POST https://api.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "password"}'
```

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

### 3. Common Response Codes

| Code | Description | Common Causes |
|------|-------------|---------------|
| 200  | Success | Request completed successfully |
| 201  | Created | Resource created successfully |
| 400  | Bad Request | Invalid request body or parameters |
| 401  | Unauthorized | Missing or invalid authentication |
| 403  | Forbidden | Authenticated but not authorized |
| 404  | Not Found | Resource does not exist |
| 429  | Too Many Requests | Rate limit exceeded |
| 500  | Internal Server Error | Server-side error |

### 4. Endpoints

#### Resource: [Resource Name, e.g., Users]

##### GET /resource
**Description**: [What this endpoint does]

**Query Parameters**:
| Parameter | Type | Required | Description | Default |
|-----------|------|----------|-------------|---------|
| `limit` | number | No | Number of results | 20 |
| `offset` | number | No | Pagination offset | 0 |

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

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

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

---

##### POST /resource
**Description**: [What this endpoint does]

**Request Body**:
```json
{
  "field1": "value",
  "field2": 123
}
```

**Validation Rules**:
- `field1`: Required, 2-100 characters
- `field2`: Required, positive integer

**Response (201 Created)**:
```json
{
  "id": 124,
  "field1": "value",
  "field2": 123,
  "created_at": "2024-01-20T12:00:00Z"
}
```

---

##### PUT /resource/:id
**Description**: [What this endpoint does]

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

**Request Body** (all fields optional):
```json
{
  "field1": "new value"
}
```

**Response (200 OK)**:
```json
{
  "id": 124,
  "field1": "new value",
  "updated_at": "2024-01-21T09:15:00Z"
}
```

---

##### DELETE /resource/:id
**Description**: [What this endpoint does]

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

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

---

### 5. 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

**Example Response Headers**:
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1640000000
```

### 6. Webhooks (Optional)

[Description of webhook system if applicable]

**Webhook Events**:
- `resource.created` - Triggered when a new resource is created
- `resource.updated` - Triggered when a resource is updated
- `resource.deleted` - Triggered when a resource is deleted

**Webhook Payload Example**:
```json
{
  "event": "resource.created",
  "timestamp": "2024-01-20T12:00:00Z",
  "data": {
    "id": 124,
    "field1": "value"
  }
}
```

---

## Rules

1. **Include only relevant sections** - Skip Part A for pure web services, skip Part B for pure libraries
2. **Signatures only in Part A** - No implementation code in Code API section
3. **Complete examples in Part B** - All HTTP examples should be runnable
4. **Consistent formatting** - Use language-specific code blocks (TypeScript, HTTP, JSON, bash)
5. **Brief descriptions** - One line per item is sufficient for Code API
6. **Detailed explanations for HTTP** - Include request/response examples, validation rules, error cases
7. **Alphabetical order** - Sort items within each section for easy lookup
8. **Public API only** - Do not document internal/private exports or endpoints

---

## Template Usage Guidelines

### For Module-Level API.md (Code API)
**Use**: Part A only
**Location**: `modules/[module-name]/API.md`
**Focus**: Exported functions, classes, interfaces

### For Project-Level HTTP API Documentation
**Use**: Part B only
**Location**: `.workflow/docs/api/README.md`
**Focus**: REST/GraphQL endpoints, authentication

### For Full-Stack Projects (Both Code and HTTP APIs)
**Use**: Both Part A and Part B
**Organization**:
- Part A for SDK/client library APIs
- Part B for HTTP endpoints

---

**Last Updated**: [Auto-generated timestamp]
**API Version**: [Version number]
**Module/Service Path**: [Auto-fill with actual path]