api-design

# API Design Skill > **Expertise:** REST API design, HTTP semantics, versioning strategies, error contracts, OpenAPI, pagination, idempotency. ## HTTP Method & Status Code Reference | Operation | Method | Success | Error cases | |---|---|---|---| | Create resource | POST | 201 Created | 400 Validation, 409 Conflict | | Read resource | GET | 200 OK | 404 Not Found, 403 Forbidden | | Full update | PUT | 200 OK | 400, 404, 409 | | Partial update | PATCH | 200 OK | 400, 404 | | Delete | DELETE | 204 No Content | 404, 409 (has dependents) | | Async action | POST | 202 Accepted | 400 | ## URL Design Rules ``` ✅ Nouns, plural, lowercase, kebab-case GET /users/{id} POST /orders GET /product-categories ❌ Verbs in path POST /createOrder GET /getUser?id=123 ✅ Nesting only for true ownership (max 2 levels) GET /orders/{order_id}/items ✅ items belong to order GET /orders/{order_id}/items/{item_id}/tags ❌ too deep ✅ Actions as sub-resources POST /orders/{id}/cancel POST /invoices/{id}/resend ``` ## Standard Error Contract All error responses must follow the same shape: ```json { "error": { "code": "ORDER_NOT_FOUND", // machine-readable, stable "message": "Order ord_123 not found", // human-readable "details": [ // optional: per-field errors { "field": "items[0].quantity", "issue": "must be > 0" } ], "request_id": "req_abc123" // traceable } } ``` ```python # FastAPI impl...