API Design

Aim for boring, predictable APIs. Consistency beats cleverness — a caller should be able to guess the next endpoint.

Resources & methods

• Name resources as plural nouns: /users, /users/{id}, /users/{id}/orders.
• Map methods to intent: GET (read, safe), POST (create/action), PUT (full replace), PATCH (partial update), DELETE (remove). GET/PUT/DELETE should be idempotent.
• Avoid verbs in paths (/createUser ✗). For non-CRUD actions, POST a sub-resource (POST /orders/{id}/refund).

Status codes (use the right one)

• 200 OK, 201 Created (+ Location), 202 Accepted (async), 204 No Content.
• 400 bad input, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 422 validation failed, 429 rate-limited (+ Retry-After).
• 500 server error (never leak internals), 503 unavailable.