api-design-checklistlisted

## Purpose An API that's internally consistent is easier to learn, easier to generate clients for, and produces fewer "wait, why does this endpoint work differently" bugs. This skill is a checklist to run a new or changed endpoint against so it fits the shape of everything around it, rather than introducing its own one-off convention. ## When to use it Whenever you're adding a new endpoint, changing the shape of an existing one, or reviewing someone else's API change. Also useful as a gut-check when something about an endpoint feels awkward to call — that friction is often a naming or shape inconsistency. ## Naming - Use plural nouns for collections (`/orders`, not `/order`), and nest resources under their natural parent (`/orders/{id}/line-items`, not `/line-items?order_id=`) when the child genuinely can't exist without the parent. - Keep casing consistent across the whole API for URL segments, query params, and JSON field names — pick one convention (commonly `kebab-case` for URLs, `snake_case` or `camelCase` for JSON body fields) and don't let a new endpoint drift to a different one. - Use HTTP methods for verbs, not the URL — `POST /orders/{id}/cancel` is more debatable than `PATCH /orders/{id}` with a status field, but either way stay consistent with how the rest of the API expresses state transitions. ## Status codes - `200` for a successful read or update that returns a body, `201` for a successful creation (with a `Location` header or the created resource in th