API Design — Naming, Paths, Routing & Contracts
Interviewers rarely ask you to design REST. They ask whether /getUser is wrong, how deep nesting should go, when to version, which status codes clients can trust, and how you paginate without breaking caches. This hub maps naming, nesting, methods/status, versioning, and list contracts.
- 1Gist
- 2Maps
- 3Q&A
- 4Sandbox
Voice readout needs Web Speech Synthesis in this browser.
How you shape the public surface
Prefer
Resource-oriented nouns, verbs in methods, actions only when CRUD fails
Durable entities get collection/item URLs and uniform GET/POST/PUT/PATCH/DELETE. Workflows that are not replace-or-create get a documented custom action. Reads stay cacheable GETs with stable query params.
- Cacheable GETs, authz by resource type + id, OpenAPI generators stay boring.
- Hybrid is fine: CRUD for nouns plus :customAction for business verbs.
- Client POST retries are a pointer to the Idempotency cluster — not a second lesson here.
Alternative
RPC verbs in every path, or GraphQL as a default
/rpc/CreateOrder and /getUser map 1:1 to procedures. They fight HTTP caches, authorization grids, and client codegen. GraphQL is a different caching and authz story — one comparative note, not this cluster.
- Path verbs hide whether the call is safe, cacheable, or a mutation.
- Deep RPC trees duplicate what method + noun already said.
- Interviewers ding /getX, 200-for-everything, and unversioned breaks.
Request path this cluster designs
Gateway matching and resource handlers — not idempotency keys or OAuth.
- 1
Name the noun
Plural collection, opaque item id, filters in the query string. Depth: naming lesson. - 2
Bound the tree
Nest for ownership; flatten first-class lists. Custom actions for non-CRUD. Depth: nesting lesson. - 3
Pick method + status
Collections vs items, 201 Location, Prefer, If-Match. Depth: methods lesson. - 4
Evolve without surprise
Additive first. Version only when old clients cannot ignore the change. Depth: versioning. - 5
Page the list
Stable sort, cursor or offset, sparse fields, Link rel=next. Depth: pagination.
Overview
Interview prompt: sketch the HTTP API. Seniors are graded on consistency you can defend — not on reciting Fielding.
This cluster is additive to the existing Idempotency topic. We design the surface those retries hit. We do not re-teach Idempotency-Key, fingerprint mismatch, outbox/inbox, or OAuth.
Rule of thumb:
- Mostly CRUD on durable entities → resource paths + standard methods.
- Multi-step workflow / non-CRUD business verb → action endpoint, not a fake
POSTthat pretends to be a collection create. - Public, cacheable reads →
GET+ stable query params +ETag/If-None-Match. - Need compatibility forever → prefer additive changes; version only on breaking contracts.
- Client retries
POST→ idempotency keys and HTTP method truth; pointer only here.
You should be able to:
- Classify a path as resource-oriented, RPC-verb-in-path, custom action, or too deep.
- Say why GraphQL is a cousin, not a substitute for this whiteboard.
- Point at the five sibling pages instead of dumping every rule on one slide.
Resource-oriented vs RPC vs hybrid
| Style | Path shape | When it wins | What you give up |
|---|---|---|---|
| Resource-oriented | /orders/{id} + HTTP method | CRUD nouns, cacheable GETs, uniform authz | Awkward for “void + notify + ledger” |
| RPC / action | /rpc/CreateOrder | Non-CRUD workflows, one procedure | Weak HTTP cache semantics |
| GraphQL | single /graphql | Many client shapes, over-fetch pain | Different authz/caching (hub note only) |
| Hybrid | CRUD + :void or /actions | Real products | Need a convention, not soup |
Hybrids are common and fine if documented. Interviews reward one rule applied everywhere.
Architecture — method + path template
Flow
- 1
1 Client SDK / browser
- next2 API gateway
- 2
2 API gateway
- next3 Match method + path
- 3
3 Match method + path
- next4 Resource handler
- 4
4 Resource handler
- next5 Authz + validate
- 5
5 Authz + validate
- next6 Load page / filter
- 6
6 Load page / filter
- next7 200 + Link next
- 7
7 200 + Link next
Lesson map
API Design — Naming, Paths, Routing & Contracts
Interviewers rarely ask you to design REST. They ask whether /getUser is wrong, how deep nesting should go, when to version, which status codes clients can trust, and how you paginate without breaking caches. This hub maps naming, nesting, methods/status, versioning, and list contracts.
Architecture. Architecture
Select a node to see why it exists, or an edge to see the protocol, direction, effect, and consequence.
Mermaid export
flowchart TB c["1 Client SDK / browser"] gw["2 API gateway"] rt["3 Match method + path"] h["4 Resource handler"] c -->|1 Client SDK / browser| gw gw -->|2 API gateway to 3 Match method + path| rt rt -->|3 Match method + path| h
Edge rewrite must preserve identity segments. Authz runs on the resource the template named, not on a stripped internal path. Depth: nesting & gateways.
Cluster map
- Naming & URIs — plurals, case, opaque IDs, path vs query.
- Nesting, routing, actions — depth ~2–3,
:customAction, rewrite/IDOR. - Methods & status — collections vs items, 201, Prefer, If-Match, problem+json.
- Versioning — URL vs header vs query; Sunset; when not to version.
- Pagination — offset vs cursor, stable sort, sparse fieldsets.
What interviewers ding across all five: /getX, deep nesting, 200-for-everything, unversioned breaking changes, offset pagination without a stable sort.
Sandbox: classify path style (Python)
Conceptual interview helper — not a linter. Verbs in the path, Google-style :action, and six-plus slash segments are the usual tells.
Press Run. Snippets must be self-contained — no network, files, or native modules.
Same classifier (TypeScript)
Press Run. Snippets must be self-contained — no network, files, or native modules.
Deep dive · Where idempotency fits — pointer only
Safe retries for POST need keys and fingerprints. That contract lives in API idempotency keys, request fingerprinting, retry storms, and idempotent HTTP methods. Rate-limit language is 429 / Retry-After. This cluster does not re-teach those state machines.
Pitfalls
Sketch Order, Invoice, and void. Where is the noun? Where is the action? Which URLs are cacheable GETs? Which POSTs need an idempotency pointer rather than a new lesson?
Interview Q&A
REST or RPC?
Answer
Use resource CRUD when the domain is nouns; use RPC/actions for non-CRUD workflows. Hybrids are common and fine if documented. Interviews grade the rule, not the religion.
Why no verbs in paths?
Answer
Verbs belong in the method. Path verbs fight cacheability, authorization grids, and client generators. POST /orders plus POST /invoices/{id}:void is the hybrid that still reads as HTTP.
How does this relate to idempotency?
Answer
Safe retries for POST need keys and fingerprints — see idempotency keys and idempotent HTTP methods. This cluster designs the surface those retries hit. Do not re-teach the key state machine here.
When is GraphQL better?
Answer
Many client shapes and REST over-fetch pain. Accept different caching and authz complexity. One comparative note — not this cluster's focus.
What do interviewers ding?
Answer
/getX, deep nesting, 200-for-everything, unversioned breaking changes, and offset pagination without a stable sort.
CRUD on a collection vs a custom action?
Answer
Create/list/replace/delete stay on /orders and /orders/{id}. Void, approve, and send-invoice are not replace — use :action or /actions. Depth: nesting.
Do public APIs always need /v1?
Answer
No. Prefer additive evolution. Version when old clients cannot safely ignore the change. Depth: versioning.
Where do filters live?
Answer
Query string, not /orders/status/paid unless status is a real resource. Identity in the path. Depth: naming.
Why does the gateway sit in the diagram?
Answer
It matches method + path template and may rewrite prefixes. Rewrites that drop {orgId} become IDOR. Depth: routing.
Always-200 envelopes?
Answer
Easy for naive clients; they break caches, CDNs, and HTTP tooling. Prefer real status codes plus problem+json. Depth: methods & status.