api-design

# API Design ## Instructions ### Step 1: Gather Requirements Ask: 1. What resources does this API manage? (e.g., users, orders, products) 2. What operations are needed? (CRUD, search, bulk operations, async jobs) 3. Who consumes it? (internal services, public clients, mobile apps) 4. Auth model? (API key, OAuth2, JWT) 5. Output format preference? (OpenAPI 3.0 YAML, endpoint list, or both) ### Step 2: Resource Naming Apply these naming conventions: | Rule | Good | Bad | |------|------|-----| | Plural nouns | `/users` | `/user`, `/getUsers` | | Nested resources | `/users/{id}/orders` | `/getUserOrders` | | Lowercase with hyphens | `/order-items` | `/orderItems`, `/order_items` | | No verbs in URLs | `/users/{id}/activate` (POST) | `/activateUser` | | Max 3 levels deep | `/users/{id}/orders` | `/users/{id}/orders/{id}/items/{id}/reviews` | For deeply nested resources, promote to top-level with query filters: ``` GET /reviews?order_id=123&user_id=456 ``` ### Step 3: HTTP Methods and Status Codes Map operations to methods: | Operation | Method | Success Code | Response Body | |-----------|--------|-------------|---------------| | List/Search | GET | 200 | Collection | | Get single | GET | 200 | Resource | | Create | POST | 201 | Created resource + Location header | | Full update | PUT | 200 | Updated resource | | Partial update | PATCH | 200 | Updated resource | | Delete | DELETE | 204 | Empty | | Async operation | POST | 202 | Job status + Location header | **Error cod...