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 request/response schemas, documented errors.

```
✅ Documented required fields
✅ Consist