api-design-patterns

REST and GraphQL API design patterns.

Mandatory Rules (Blocking — violating any is an error)

1. Every endpoint MUST return a consistent error envelope: { "error": { "code": "...", "message": "...", "details": [...] } }
2. Never expose internal IDs in URLs without validation — all path params must be validated (UUID format, existence check)
3. Never return 200 for errors — use proper 4xx/5xx status codes
4. Every collection endpoint MUST support pagination — no unbounded lists
5. Every mutating endpoint MUST be idempotent or document why not — include Idempotency-Key header support for POST
6. Never break backwards compatibility — additive changes only without version bump
7. Every endpoint MUST have rate limiting — return 429 with Retry-After header
8. No sensitive data in URLs — tokens, passwords, PII go in headers or body, never query params
9. All responses MUST include request-id header — for tracing and debugging
10. OpenAPI spec MUST exist — no endpoint without a spec entry

Forbidden Patterns (Anti-patterns to reject on sight)