api-design

# API Design ## Purpose Design HTTP APIs that clients can use correctly without reading your source code, and that you can evolve without breaking them. ## When to Use - Designing a new API or a new endpoint on an existing one. - Reviewing an API before it becomes public and therefore permanent. - Introducing versioning, pagination, or idempotency to an API that lacks them. - Writing or auditing an OpenAPI specification. ## Capabilities - Resource and URL modeling. - Status-code semantics and consistent error payloads (RFC 9457 problem details). - Pagination strategies and their trade-offs. - Idempotency for unsafe methods. - Versioning and deprecation without breaking clients. - OpenAPI specification as the source of truth. ## Inputs - The domain operations the API must expose. - Client types: first-party, third-party, mobile, machine. - Expected volume, page sizes, and latency requirements. ## Outputs - An OpenAPI 3.1 specification. - Consistent error and pagination formats across every endpoint. - A documented versioning and deprecation policy. ## Workflow 1. **Model resources, not procedures** — `POST /orders/{id}/refunds` rather than `POST /refundOrder`. When an operation genuinely is not a resource, it is fine to say so, but check first. 2. **Fix the status codes** — 200 for a body, 201 with a `Location` for creation, 202 for accepted-but-not-done, 400 for malformed, 401 versus 403 correctly, 409 for conflict, 422 for semantically invalid, 429 with `Retry-Af...