rest-api-designlisted

# REST API Design A good REST API is **guessable**: once a consumer learns one endpoint, they can predict the rest. This skill is the deep reference for designing one — the principles, the decisions, the trade-offs, and the mistakes to avoid. Heavy detail lives in `references/`; copy-paste material in `examples/`; a runnable contract check in `scripts/`. ## Mental model Design the API around **resources** (nouns) and use HTTP **verbs** to act on them. The protocol already gives you a rich vocabulary — methods, status codes, headers, caching — so lean on it instead of inventing your own conventions on top. | Concern | REST answer | |---|---| | What | a resource, named as a plural noun (`/orders`) | | Action | the HTTP method (GET/POST/PUT/PATCH/DELETE) | | Outcome | the status code (200/201/404/409…) | | Shape | a consistent response envelope | | Change | an explicit versioning strategy | ## 1. Resource modeling 1. Name collections as **plural nouns**: `/users`, `/orders`. Never verbs in the path (`/getUsers` is wrong — the verb is `GET`). 2. Nest to show ownership, but only **one level deep**: `/users/{id}/orders` is fine; `/users/{id}/orders/{id}/items/{id}/...` is a smell — link instead. 3. Model real-world actions that aren't CRUD as sub-resources or controller endpoints: `POST /orders/{id}/refunds` rather than `POST /refundOrder`. 4. Keep identifiers stable and opaque to clients; don't leak DB internals (prefer UUIDs/ULIDs over auto-increment IDs where enumeration i