REST API Design

API designed for the developer-client. KISS, standard vocabulary, predictable shapes — expose what clients need, not the internal data model.

Non-negotiables (never omit from an answer)

1. 422 = schema/type invalid; 400 = valid body but illegal operation (insufficient balance, already shipped); 409 = state collision (concurrent edit, duplicate). Name all three when choosing one.
2. State-changing side effects (payments, orders, sends) must take Idempotency-Key; replay the stored response, cache 2xx/4xx, allow retry on 5xx.
3. Every error body must carry a machine-readable error_code, a human message and field-level details for validation.
4. Creation returns 201 + Location:; delete returns 204; never 2xx on error.
5. Lists are paginated from day one; filter/sort/expand fields are whitelisted server-side.

Workflow

1. Identify resources — nouns, plural, ≤2 levels of nesting
2. Map operations to HTTP verbs + status codes (table below)
3. Define pagination / filter / error envelope / auth upfront, not retrofitted
4. Document with copy-paste-ready curl examples per endpoint