api-design

<!-- This is a SCAFFOLD skill --> # API Design ## When to Apply - **Classification**: feature, architecture-change, hotfix (if touching API endpoints) - **Phase**: /implement (design & build), /review (compliance check), /test (contract verification) - **Trigger**: Task involves creating, modifying, or deprecating API endpoints ## Conventions > **Customize after /app-init**: Replace these generic conventions with your project's ADR decisions. ### Endpoint Naming - Use nouns for resources, not verbs: `GET /users` not `GET /getUsers` - Plural resource names: `/users`, `/orders`, `/products` - Nested resources for relationships: `/users/:id/orders` - Use kebab-case for multi-word paths: `/order-items` ### HTTP Methods | Action | Method | Success Status | Idempotent | |---|---|---|---| | List | GET | 200 | Yes | | Get one | GET | 200 | Yes | | Create | POST | 201 | No | | Full update | PUT | 200 | Yes | | Partial update | PATCH | 200 | No | | Delete | DELETE | 204 | Yes | ### Error Response Format ```json { "error": { "code": "VALIDATION_ERROR", "message": "Email is required", "details": { "field": "email", "constraint": "required" } } } ``` ### Standard Error Codes | HTTP Status | When | Error Code Pattern | |---|---|---| | 400 | Invalid input | VALIDATION_ERROR, INVALID_FORMAT | | 401 | Not authenticated | UNAUTHORIZED | | 403 | Not permitted | FORBIDDEN | | 404 | Resource not found | NOT_FOUND | | 409 | Conflict (duplicate) | CONFLICT, ...