api-design

# API Design

Design clear, consistent, and developer-friendly REST APIs.

## Design Process

```
┌──────────────────────────────────────────────────────────────────┐
│                      API DESIGN PROCESS                          │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  1. RESOURCES         2. OPERATIONS       3. CONTRACTS          │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
│  │ Identify    │  →  │ Define CRUD │  →  │ Request/    │       │
│  │ entities    │     │ + actions   │     │ Response    │       │
│  │ & relations │     │ + methods   │     │ schemas     │       │
│  └─────────────┘     └─────────────┘     └─────────────┘       │
│                                                                  │
│  4. ERRORS            5. DOCS             6. REVIEW             │
│  ┌─────────────┐     ┌─────────────┐     ┌─────────────┐       │
│  │ Status codes│  →  │ OpenAPI     │  →  │ Consistency │       │
│  │ Error format│     │ Examples    │     │ Usability   │       │
│  │ Edge cases  │     │ Descriptions│     │ Security    │       │
│  └─────────────┘     └─────────────┘     └─────────────┘       │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
```

## Core Principles

### 1. Resource-Oriented Design
Design around resources (nouns), not actions (verbs).

```
✅ GET  /users/123/orders     → Get user's orders
✅ POST /orders               → Create order

❌ GET  /getUserOrders?id=123 → Action in URL
❌ POST /createOrder          → Verb in URL
```

### 2. Predictable Patterns
Consistent URL structure, response format, and behavior.

```
✅ All collections: GET /resources
✅ All items: GET /resources/{id}
✅ All creates: POST /resources
✅ All updates: PUT/PATCH /resources/{id}
✅ All deletes: DELETE /resources/{id}
```

### 3. Clear Contracts
Explicit reques