api-designlisted

# API Design A well-designed API is one a consumer can correctly guess the shape of before reading the docs, because it follows conventions consistently rather than inventing a new pattern per endpoint. Most of what makes an API "good" is this kind of predictability, not cleverness. ## Resource naming and structure **Nouns for resources, HTTP methods for actions.** `/orders/123` plus `DELETE` is more consistent than `/deleteOrder/123` — the URL names the *thing*, the HTTP method names the *operation* on it. A URL with a verb baked in (`/getUser`, `/createOrder`) is usually a sign the API is modeling procedures instead of resources, which tends to produce an unpredictable, ad hoc endpoint list rather than a consistent pattern consumers can extrapolate from. **Plural nouns, consistently.** `/orders` not `/order` for the collection, `/orders/123` for a single item — pick one convention and never mix singular and plural across endpoints; the inconsistency forces a consumer to memorize each endpoint individually rather than infer the pattern. **Nest resources to express genuine ownership, but don't nest too deep.** `/orders/123/line-items` expresses that line items belong to a specific order — reasonable. `/customers/1/orders/123/line-items/5/discounts` is deep enough that it's fighting the URL structure to express what should probably be a flatter model with its own top-level resource and a filter, e.g., `/line-items/5/discounts?order=123`. A rough guide: if you need more th