Resource Naming & URI Design — Plurals, Case, IDs & Collections
Almost every API design interview starts with a path sketch. Interviewers check plural nouns, verbs smuggled into URLs, kebab vs snake consistency, opaque IDs, and whether filters live in the query string. We design the nouns idempotent retries operate on — without re-teaching Idempotency-Key.
- 1Gist
- 2Maps
- 3Q&A
- 4Sandbox
Voice readout needs Web Speech Synthesis in this browser.
How you name the resource
Prefer
Plural collection, opaque id, filters in the query
/orders and /orders/ord_1a2b. Status and owner are query params. Gateway lowercases and strips a trailing slash so caches see one resource.
- Opaque IDs hide cardinality, survive shards, and skip enumeration.
- Prefixes (usr_, ord_) help support and routers.
- Query is for optional narrowing — not a second identity scheme.
Alternative
Singular verbs, sequential ids, filters in the path
/getUser, /orders/42, /orders/status/paid. Looks like a controller dump. Authz matrices and OpenAPI explode. Integers leak growth and invite scraping.
- Mixed /Users, /user-profiles, /user_settings fail codegen.
- Email-as-id without a rename policy 404s paying customers.
- Trailing-slash variants split CDN caches.
URI from domain noun
Identity in the path. Everything else is a query.
- 1
Pluralize lowercase
Order → /orders. Pick kebab-case or snake_case once. - 2
Add opaque id
/orders/ord_1a2b or a UUID. Sequential 42 is a last resort. - 3
Filters in query
?status=paid&limit=50 — not /orders/status/paid. - 4
Normalize at the edge
Case and trailing slash. One cache key, one authz row.
Overview
Almost every API design interview starts with a path sketch. Getting URI design right signals you have shipped client SDKs and thought about authz matrices, OpenAPI generators, and caching.
This lesson is additive to the Idempotency cluster — we design the nouns those retries operate on, without re-teaching Idempotency-Key mechanics.
Core rules:
- Plural nouns for collections:
/users,/orders— not/userunless the whole API is singular (rare; stay consistent). - Lowercase path segments; prefer kebab-case (
/rate-limits) or snake_case (/rate_limits) — pick one and enforce. - No verbs in paths:
POST /ordersoverPOST /createOrderorGET /getUser. - Collection vs item:
/orders(list/create) vs/orders/{orderId}(read/replace/delete). - Opaque IDs in production paths:
ord_1a2b/ UUIDs beat/orders/42when IDs leak or collide across shards. - Readable slugs OK for public CMS-style resources (
/posts/api-design-101) if uniqueness and rename policy are clear. - Trailing slash: pick one policy and normalize at the gateway — do not treat
/usersand/users/as different resources. - Path params = identity; query params = filter/sort/page/field selection.
Opaque IDs vs integers vs slugs
| ID style | Pros | Cons |
|---|---|---|
Opaque prefixed (ord_1a2b) / UUID | No PII, shard-friendly, rename-safe | Harder to debug by eye — prefixes help |
| Sequential integers | Simple | Enumeration, merge collisions, leak growth |
| Public slugs | Human URLs for CMS | Need canonical id + redirect on rename |
Never put secrets in path or query (access logs, proxies, Referer). Use headers or body.
Path vs query
- Identity / hierarchy → path:
/orgs/{orgId}/projects/{projectId}(when nesting is warranted — next lesson). - Optional narrowing → query:
/projects?status=active&owner=u_9. - Not a resource:
/orders/status/paidtreats a filter as hierarchy. Prefer/orders?status=paid.
Flow
- 1
1 Domain noun
- next2 Plural collection
- 2
2 Plural collection
- next3 Opaque item id
- 3
3 Opaque item id
- next4 Filters in query
- 4
4 Filters in query
- next5 Normalize slash/case
- 5
5 Normalize slash/case
- next6 Authz type + id
- 6
6 Authz type + id
Lesson map
Resource Naming & URI Design — Plurals, Case, IDs & Collections
Almost every API design interview starts with a path sketch. Interviewers check plural nouns, verbs smuggled into URLs, kebab vs snake consistency, opaque IDs, and whether filters live in the query string. We design the nouns idempotent retries operate on — without re-teaching Idempotency-Key.
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 n["1 Domain noun"] c["2 Plural collection"] i["3 Opaque item id"] q["4 Filters in query"] n -->|1 Domain noun to 2 Plural collection| c c -->|2 Plural collection| i i -->|3 Opaque item id to 4 Filters in query| q
Sandbox: URI builder with guardrails (Python)
Naive pluralization is fine on a whiteboard if you say so. Production uses real inflection and an allow-list of collection names.
Press Run. Snippets must be self-contained — no network, files, or native modules.
Same guardrails (TypeScript)
Press Run. Snippets must be self-contained — no network, files, or native modules.
Pitfalls
/posts/api-design-101 becomes /posts/api-design-202. What 301s? What stays in SDKs? Store a canonical opaque id and redirect the slug.
Interview Q&A
Plural or singular?
Answer
Prefer plurals for collections. Consistency beats linguistic purity. Document the rule so /people vs /persons is a style guide, not a debate.
Why opaque IDs?
Answer
Avoid enumeration, hide cardinality, survive merges and sharding. Prefixes help humans and routers (usr_, ord_). Integers leak growth and invite scraping.
Path or query for status=active?
Answer
Query — it is a filter, not the resource's identity. Path is for /orders/{orderId} and true parent/child ownership (next lesson).
Are slugs OK?
Answer
For public, rename-tolerant content yes. Store a canonical id and redirect on slug change so bookmarks and CDNs converge.
Kebab or snake?
Answer
Either. Enforce with linting in OpenAPI. Interviews care about consistency, not which delimiter you married.
Why not /users/me as the only self URL?
Answer
/users/me is a convenient alias. Still expose /users/{id} as canonical so tokens, admin tools, and logs share one identity. Overlapping templates need explicit priority — nesting.
Can I use email in the path?
Answer
Only with a documented encoding and rename policy. Emails change; they also leak PII into logs. Prefer usr_ + lookup-by-email as a filter or a POST search.
Trailing slash?
Answer
Pick /users or /users/, normalize at the gateway, one cache key. RFC 3986 treats them as different URIs if you do nothing.
How do HTTP methods sit on these URIs?
Answer
GET/POST /orders, GET/PUT/PATCH/DELETE /orders/{id}. Method truth: HTTP methods and idempotent methods.
What about /v1 in the path?
Answer
That is a versioning choice, not a naming choice. Keep this page on nouns; see versioning.