api-designer

> **AI-consumed reference.** Optimized for Claude to read during execution. > Human-readable explanation: see [docs/architecture/HIERARCHICAL_PLANNING.md](../../../docs/architecture/HIERARCHICAL_PLANNING.md) > or [docs/getting-started/](../../../docs/getting-started/) depending on topic. # Skill: API Designer Design consistent, RESTful APIs with versioning, documentation, and error handling. --- ## RESTful Conventions | Method | Endpoint | Purpose | Response | |--------|----------|---------|----------| | GET | /users | List | 200 + array | | GET | /users/:id | Get one | 200 / 404 | | POST | /users | Create | 201 + created | | PUT | /users/:id | Replace | 200 / 404 | | PATCH | /users/:id | Update | 200 / 404 | | DELETE | /users/:id | Delete | 204 / 404 | Nested: `GET /users/:userId/orders` --- ## Naming - Resources: plural nouns (`/users`, `/orders`) - Query params: snake_case (`page_size`) - Request/Response bodies: camelCase **Versioning:** URL path `/api/v1/...` (recommended). --- ## Response Format **Success:** `{ "data": {...}, "meta": {...} }` **List:** Add `meta: { page, pageSize, total, totalPages }` **Error:** `{ "error": { "code": "VALIDATION_ERROR", "message": "...", "fields": {...} } }` --- ## Status Codes | Code | When | |------|------| | 200 | Successful GET/PUT/PATCH | | 201 | Successful POST | | 204 | Successful DELETE | | 400/422 | Invalid input / validation | | 401/403 | No auth / no permission | | 404/409 | Not found / conflict | | 429 | Rat...