REST API Design

"Design the API" appears inside nearly every system design round, and as its own screen for backend roles. The grading is mostly about consistency and failure handling, not REST purity: do your methods match their semantics, do you return the right status codes, can a client retry safely (idempotency), and does the API survive growth (pagination, versioning) without breaking existing clients. Two vocabulary words to wield precisely - safe = no server state change (GET, HEAD); idempotent = N identical requests have the same effect as one (everything except POST and PATCH, by contract).

GET

Read a resource. Safe, idempotent, cacheable. Never mutate on GET - crawlers and prefetchers will execute it for you.

HEAD

GET without the body - headers only. Existence checks, size probes before download.

POST

Create a subordinate resource or trigger a process. NOT idempotent by default - the double-submit problem. Make it retry-safe with an Idempotency-Key header (Stripe-style: server stores key -> first response, replays return it). Returns 201 + Location on create.

PUT

Full replace at a client-known URI. Idempotent - PUT the same document twice, same end state. Sending a partial body and calling it PUT is the classic semantics violation; that's PATCH.

PATCH

Partial update. Not guaranteed idempotent (a JSON Patch "append to array" op isn't; a merge-patch of fields usually is). Formats: JSON Merge Patch (RFC 7386, simple) vs JSON Patch (RFC 6902, op-list).

DELETE

Remove the resource. Idempotent in effect - deleting twice leaves the same state; the second call may honestly return 404, which clients should treat as success.

OPTIONS

Capability discovery; what CORS preflight uses. You mostly just need to not break it.

200 OK

Generic success with a body. The default for reads and updates.

201 Created

Resource created - return a Location header pointing at it, and usually the representation.

202 Accepted

Work queued, not done - async processing. Return a status URL the client can poll.

204 No Content

Success, nothing to say. DELETEs and side-effect-only updates.

301 / 308

Permanent redirect. 308 preserves the method (a POST stays a POST); 301 lets clients downgrade to GET.

304 Not Modified

Conditional GET hit: client's ETag (If-None-Match) still current. Free bandwidth via caching.

400 Bad Request

Malformed request - unparseable JSON, missing required field, bad types.

401 Unauthorized

Misnamed: means unauthenticated - no/invalid credentials. "Who are you?"

403 Forbidden

Authenticated but not allowed. "I know who you are - no." (Some APIs return 404 instead, to avoid leaking that the resource exists.)

404 Not Found

No such resource. Also the polite mask for 403 on private resources.

409 Conflict

Request conflicts with current state: duplicate unique key, version conflict, state machine violation (cancelling a shipped order).

412 Precondition Failed

Conditional write lost the race: If-Match ETag is stale. The HTTP face of optimistic concurrency.

422 Unprocessable Entity

Parseable but semantically invalid - email field that isn't an email. Common split: 400 = can't parse, 422 = parsed but invalid. Pick one convention and apply it everywhere.

429 Too Many Requests

Rate limited. Include Retry-After and rate-limit headers (see below).

500 Internal Server Error

Unhandled server fault. Return a correlation/request ID in the body; never a stack trace.

502 / 503 / 504

Upstream spoke garbage (502: bad gateway) / service overloaded or in maintenance, retry later (503, with Retry-After) / upstream timed out (504). Knowing which is which signals production experience.

• ·Nouns, not verbs: POST /orders, not /createOrder. The method is the verb.
• ·Plural collections, ID for members: /users and /users/123. Pick plural and never mix.
• ·Nest only for true ownership, one level deep: /users/123/orders is fine; /users/123/orders/456/items/789/reviews is not. Once a child has its own identity, give it a top-level home: /orders/456.
• ·Lowercase kebab-case in paths (/credit-notes), snake_case or camelCase in JSON bodies - choose one body convention and enforce it API-wide.
• ·Filtering, sorting, pagination via query params: GET /orders?status=shipped&sort=-created_at&cursor=abc. Path = identity, query = view.
• ·Non-CRUD actions: prefer state changes on the resource (POST /orders/123/cancellation, or PATCH status) over RPC-ish verbs. If you must, a scoped action endpoint - POST /orders/123:cancel - beats a global /cancelOrder.
• ·No file extensions, no trailing-slash ambiguity, and never expose internal DB ids if enumeration is a risk - use UUIDs/slugs.
• ·Searches with huge criteria: POST /searches creating a search resource sidesteps URL length limits without pretending POST is GET.
• ·Consistency beats elegance: a mediocre convention applied uniformly is a better API than a clever one applied 80% of the time.

type

URI identifying the error category (https://api.example.com/errors/insufficient-funds). Doubles as a documentation link. Stable - clients switch on this, not on prose.

title

Short human-readable summary of the category. Doesn't change per occurrence.

status

The HTTP status code, repeated in the body for logs and proxies.

detail

Human-readable explanation of this occurrence: "Balance is $30, transfer was $50." Never a stack trace, never internal class names.

errors[] (extension)

Field-level validation details for 400/422: [{ "field": "email", "code": "invalid_format", "message": ... }]. Lets a form highlight every bad field in one round trip.

requestId (extension)

Correlation ID echoed from the request or generated. The single highest-value field for support: "give me the requestId" replaces guesswork.

Anti-patterns

200 with { "error": ... } in the body (breaks every HTTP-aware client and cache); different error shapes per endpoint; leaking SQL/stack traces; error prose as the only signal (unparseable by clients).

429 + Retry-After

The reject path. Retry-After: 30 (seconds or HTTP date) tells well-behaved clients exactly when to come back. Also legitimate on 503.

X-RateLimit-Limit / -Remaining / -Reset

The de facto trio on every response: quota in the window, what's left, when the window resets (commonly a Unix timestamp - GitHub style). Lets clients self-throttle before hitting 429.

RateLimit-* (IETF draft)

The standardized successors (RateLimit-Limit/-Remaining/-Reset, with delta-seconds reset). Mention-worthy; X- prefixed forms still dominate in the wild.

Scope your keys

Limit per API key / user / IP - and say which in the docs. Tiered limits (free vs paid) and per-endpoint budgets (cheap reads vs expensive searches) are the expected follow-ups.

Client etiquette to design for

Retries with exponential backoff + jitter, honoring Retry-After. If you also own SDKs, build this in - thundering-herd retries after an outage are self-DDoS.

• ·Verbs in paths (/getUser, /createOrder) - the method already says it.
• ·200 OK wrapping an error payload. Status codes exist; use them.
• ·POST for everything, including reads. Breaks caching, retries, and semantics in one move.
• ·Mutations on GET. Prefetchers and crawlers will happily delete your data.
• ·No pagination on collection endpoints - works in the demo, melts at row one million.
• ·Unbounded response sizes and no field selection: clients fetch 4KB objects to read one name.
• ·Chatty resource design: N+1 round trips (/orders then /orders/{id} x 50) because the list endpoint returns only IDs. Lists should return usable summaries; consider ?include= or ?fields= for expansion.
• ·Breaking changes without a version bump: renaming/removing fields, changing types, tightening validation. Additive-only is the discipline.
• ·Inconsistent casing/shapes across endpoints (snake_case here, camelCase there; bare arrays here, { data: [...] } envelopes there).
• ·Timestamps as local time or epoch-sometimes-seconds-sometimes-millis. ISO 8601 UTC ('2026-06-10T14:30:00Z'), everywhere, no exceptions.
• ·Returning bare top-level JSON arrays - can't add metadata (pagination cursors, counts) later without breaking clients. Envelope collections from day one.
• ·Idempotency unaddressed on POST payments/orders. The follow-up is always "what happens when the client retries on timeout?"