api-design-reviewerlisted

# Review APIs before they ship Catch inconsistent conventions, missing versioning, and design smells before APIs are consumed by clients. Breaking changes are permanent costs — find them in review, not after release. ## REST design principles **Resource naming:** - Collections: plural nouns (`/users`, `/orders`) - Instances: `/{id}` (singular, no verb) - Actions that don't fit: `POST /users/{id}/activate` (not `GET /activateUser`) **HTTP method semantics:** - `GET` — read; must be idempotent; no side effects - `POST` — create or action; not idempotent - `PUT` — replace the whole resource; idempotent - `PATCH` — partial update; idempotent - `DELETE` — remove; idempotent **Status codes — common wrong choices:** | Situation | Wrong | Right | |-----------|-------|-------| | Resource not found | 200 with `{error}` body | 404 | | Validation failure | 500 | 400 with error detail | | Auth failure | 404 (hiding resource) | 401 (unauthenticated) or 403 (unauthorised) | | Created resource | 200 | 201 with `Location` header | | Async accepted | 200 | 202 | ## Breaking change detection These changes break existing clients and require a version bump: - Remove an endpoint - Remove or rename a required field - Change a field's type - Add a required field to a request body - Change a status code a client depends on - Change pagination semantics These are safe (backward-compatible): - Add a new optional field to a response - Add a new endpoint - Add a new optional query parameter ##