designing-rest-apislisted

# Designing REST APIs ## Workflow: Designing a new API 1. **Model resources as nouns.** Identify domain entities. Use plural nouns for collection URLs (`/orders`, not `/getOrders`). Express relationships with sub-resources, max 2–3 levels deep. 2. **Assign HTTP methods by semantics.** GET=read, POST=create, PUT=full replace, PATCH=partial update, DELETE=remove. For non-CRUD actions, use POST with a clear resource name (`POST /orders/7/cancellation`). 3. **Define request/response schemas.** Use camelCase for JSON fields, UPPER_SNAKE_CASE for enums, RFC 3339 for dates in UTC. Wrap collections in `{ "data": [...] }`. Use string type for IDs. Represent money as smallest currency unit + currency code. 4. **Select status codes.** Return the most specific code: `201` for creation (with `Location` header), `204` for no-content success, `409` for conflicts, `422` for business rule violations. Never return `200` with an error body. 5. **Design error responses using RFC 9457** (Problem Details). Include `type` (URI), `title`, `status`, `detail`. Return all validation errors at once. Never leak stack traces. 6. **Add pagination to every list endpoint.** Default: cursor-based pagination. Use offset pagination only for small/static datasets needing jump-to-page. Always include `has_more` or a `next` link. 7. **Plan versioning.** Use URI path versioning (`/v1/`). Only bump for breaking changes. Support at least one prior version with 6–12 month migration window. Signal deprecation via `De