api-design

# API Design Skill

Patterns for designing clean, consistent, and developer-friendly APIs.

## REST API Design

### URL Structure

```
# Collection endpoints
GET    /api/v1/users           # List users
POST   /api/v1/users           # Create user

# Resource endpoints
GET    /api/v1/users/:id       # Get user
PUT    /api/v1/users/:id       # Update user
DELETE /api/v1/users/:id       # Delete user

# Nested resources
GET    /api/v1/users/:id/posts # Get user's posts
POST   /api/v1/users/:id/posts # Create post for user

# Actions (when CRUD doesn't fit)
POST   /api/v1/users/:id/activate
POST   /api/v1/orders/:id/cancel
```

### HTTP Methods

| Method | Usage | Idempotent | Safe |
|--------|-------|------------|------|
| GET | Read resource | Yes | Yes |
| POST | Create resource | No | No |
| PUT | Replace resource | Yes | No |
| PATCH | Partial update | No | No |
| DELETE | Remove resource | Yes | No |

### Status Codes

```typescript
// Success
200 OK              // Successful GET, PUT, PATCH, DELETE
201 Created         // Successful POST (resource created)
204 No Content      // Successful DELETE (no body)

// Redirection
301 Moved Permanently
304 Not Modified    // Cache valid

// Client Errors
400 Bad Request     // Invalid input
401 Unauthorized    // Not authenticated
403 Forbidden       // Not authorized
404 Not Found       // Resource doesn't exist
409 Conflict        // State conflict (duplicate)
422 Unprocessable   // Validation failed
429 Too Many Requests // Rate limited

// Server Errors
500 Internal Error  // Unexpected error
502 Bad Gateway     // Upstream error
503 Unavailable     // Temporarily down
```

### Request/Response Format

```typescript
// Standard response envelope
interface ApiResponse<T> {
  data: T;
  meta?: {
    pagination?: Pagination;
    timestamp: string;
  };
}

// List response with pagination
interface ListResponse<T> {
  data: T[];
  meta: {
    pagination: {
      page: number;
      limit: number;
      total: number;