api-design

# API Design ## Overview Standards and patterns for designing consistent, well-documented RESTful APIs. Covers naming, HTTP methods, error handling, status codes, and documentation requirements. ## Key Concepts ### Naming Conventions - Plural nouns for resources: `/users`, `/orders`, `/products` - Kebab-case for multi-word: `/user-profiles` - Nest related resources: `/users/{id}/orders` - Query params for filtering: `/users?role=admin&active=true` ### HTTP Methods | Method | Purpose | Idempotent | Response | |--------|---------|------------|----------| | GET | Read | Yes | 200 + body | | POST | Create | No | 201 + body + Location | | PUT | Replace | Yes | 200 + body | | PATCH | Partial update | No | 200 + body | | DELETE | Remove | Yes | 204 (no body) | ### Error Response Format ```json { "error": { "code": "VALIDATION_ERROR", "message": "Human-readable description", "details": [ {"field": "email", "message": "Invalid email format"} ] } } ``` ### Status Codes - **200**: Success — **201**: Created — **204**: No content - **400**: Bad request — **401**: Unauthorized — **403**: Forbidden - **404**: Not found — **409**: Conflict — **422**: Unprocessable - **429**: Rate limited — **500**: Internal error ## Decision Framework | Scenario | Method | Path | Status | |----------|--------|------|--------| | List items | GET | /items | 200 | | Get one item | GET | /items/{id} | 200 / 404 | | Create item | POST | /items | 201 | | Full update | PUT | /items/{id} | 200 / 404 | | Partial update | PATCH | /items/{id} | 200 / 404 | | Delete item | DELETE | /items/{id} | 204 / 404 | | Search | GET | /items?q=term | 200 | | Bulk action | POST | /items/batch | 200 / 207 | ## Documentation Requirements Every endpoint must document: 1. HTTP method and path 2. Description 3. Request parameters (path, query, body) with types 4. Response schema with examples 5. Error codes and descriptions 6. Authentication requirements ## Common Pitfalls - **Using verbs in URLs** — Use nouns: `/users` not `/getUsers` - **Inconsistent error format** — Use the same error schema everywhere - **Missing pagination** — Any list endpoint that can grow needs pagination - **No versioning strategy** — Decide early: URL (`/v1/`) or header-based