api-conventionslisted

# API Conventions Load this skill when designing or implementing API endpoints. Each rule has a concrete example so reviewers can recognise the shape. ## REST Conventions - Resources are plural nouns. Actions live on HTTP methods, not in the path. ``` GOOD: GET /users POST /users GET /users/42 DELETE /users/42 BAD: GET /getUser?id=42 POST /createUser GET /user/delete?id=42 # never, ever ``` - HTTP methods map to actions. Pick one row and stick to it. | Method | Semantics | Idempotent | Has body? | |----------|----------------------------------------|------------|-----------| | `GET` | Read; no side effects | yes | no | | `POST` | Create (or non-idempotent action) | no | yes | | `PUT` | Full replace | yes | yes | | `PATCH` | Partial update | usually | yes | | `DELETE` | Remove | yes (here) | no | - Nested resources express ownership. One level deep is plenty. ``` GOOD: GET /users/42/orders BAD: GET /users/42/orders/17/items/3/refunds # design smell — flatten to /refunds/{id} ``` ## Request / Response Shape - All responses are JSON with `Content-Type: application/json; charset=utf-8`. - Success responses include a `data` key: ```json { "data": { "id": "usr_