api-design

api-design

A good API is boring: a caller who has used one endpoint can guess the next one. Consistency beats cleverness. Design the contract — URLs, status codes, request and response shapes — before you write the handler, because the contract is the part you can't change later without breaking clients.

Resources and methods

• Model nouns, not verbs. /orders/{id}/items, not /getOrderItems. The HTTP method is the verb.
• Use methods for their meaning: GET read (no side effects), POST create / non-idempotent action, PUT full replace, PATCH partial update, DELETE remove.
• GET is safe and idempotent — never mutate state in a GET. PUT, DELETE, and (ideally) PATCH are idempotent: calling twice lands in the same state. POST is not — protect creates with an idempotency key (below).
• Plural collections, stable IDs. /users, /users/{id}. Nest only for genuine ownership (/users/{id}/sessions); don't nest more than one level — prefer query filters (/sessions?user_id=…) over deep trees.

Status codes

Say what happened with the code, not just the body.

• 200 OK · 201 Created (+ Location header) · 202 Accepted (async) · 204 No Content (successful DELETE/empty).
• 400 malformed request · 401 unauthenticated · 403 authenticated but not allowed · 404 not found · 409 conflict (duplicate, version clash) · 422 well-formed but semantically invalid · 429 rate-limited (+ Retry-After).
• 500 you broke · 502/503/504 upstream/unavailable. Never return 200 with an error inside — that defeats every client's error handling.

One error shape, everywhere

Pick a single envelope and use it for every error, so clients parse one thing:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Balance 3 is below the 10 required for this action.",
    "details": { "balance": 3, "required": 10 }
  }
}

• code is a stable, machine-readable string clients branch on — it never changes wording. message is human-readable and may change. details is optional structured context (which field, which limit).
• Validation errors list every offending field at once, not just the first.
• Never leak stack traces, SQL, or internal hostnames in the message.