moai-ref-api-patterns

# API Patterns Reference ## Target Spawn Backend domain work spawned via `Agent(general-purpose)` with backend instructions - Applies these patterns directly to API implementation and review. ## RESTful API Design Conventions | Principle | Convention | Example | |-----------|-----------|---------| | Resource Naming | Plural nouns, lowercase, kebab-case | `/api/v1/user-profiles` | | Collection | GET returns array with pagination | `GET /users?page=1&limit=20` | | Single Resource | GET returns object | `GET /users/{id}` | | Create | POST to collection | `POST /users` | | Update (full) | PUT to resource | `PUT /users/{id}` | | Update (partial) | PATCH to resource | `PATCH /users/{id}` | | Delete | DELETE to resource | `DELETE /users/{id}` | | Nested Resources | Max 2 levels deep | `/users/{id}/posts` | | Filtering | Query params | `?status=active&role=admin` | | Sorting | Sort param | `?sort=-created_at,name` | | Versioning | URL prefix | `/api/v1/`, `/api/v2/` | ## HTTP Status Code Guide | Category | Code | When to Use | |----------|------|-------------| | Success | 200 OK | Successful GET, PUT, PATCH, DELETE | | Success | 201 Created | Successful POST (resource created) | | Success | 204 No Content | Successful DELETE (no body) | | Client Error | 400 Bad Request | Malformed request, validation failure | | Client Error | 401 Unauthorized | Missing or invalid authentication | | Client Error | 403 Forbidden | Authenticated but not authorized | | Client Error | 404 Not Found...