When designing URL paths for an HTTP API, what naming conventions do you follow, and why is POST /createUser considered worse than POST /users?
answer
- URL = noun, method = verb
- plural collections, id beneath
- lowercase-with-hyphens
- no .json extension — use Accept
- pick one trailing-slash form
basics
~10 sPaths name things, not actions: nouns, usually plural collections (/users, /users/42/orders). The HTTP method supplies the verb, so POST /users beats POST /createUser. Verbs in paths duplicate the method and multiply near-identical endpoints.
solid answer
~40 sA URL identifies a **resource** — a thing — so path segments are nouns and the HTTP method carries the action. `POST /users` creates, `GET /users/42` reads, `DELETE /users/42` removes. `POST /createUser`, `POST /getUser`, `POST /deleteUser` encode the verb twice and discard what HTTP already gives you: uniform semantics, safe/idempotent knowledge, cacheability of GET, and generic tooling. Conventions I apply: - **Plural collection names** (`/orders`) with the item beneath (`/orders/{id}`). - **Hierarchy for containment**: `/customers/{id}/addresses`. - **Lowercase, hyphen-separated multi-word segments**: `/purchase-orders`. - **No file extensions** (`.json`) — negotiate with the `Accept` header. - **No trailing slash**, applied consistently. The payoff is predictability: a client who has seen two endpoints can guess the third, and caches/proxies can reason about the traffic.
go deeper
Say that the path names a resource and the HTTP method is the verb, give the /users example, and mention plural collections and lowercase-hyphen segments.
Add the concrete rules — no file extensions, one trailing-slash form enforced by redirect — and explain why verbs in paths cause endpoint sprawl.
Frame it as contract predictability and tooling: consistent naming lets caches, gateways, and generated clients work without per-endpoint knowledge; call out where the convention legitimately bends.
Discuss naming as governance — a style guide plus linting on the OpenAPI spec, how you migrate a legacy verb-shaped surface, and the cost of URL churn across many client teams.
## URLs identify, methods act A URL in an HTTP API is an **identifier for a resource** — a noun-like thing: a user, an order, a collection of orders. The *action* is carried by the HTTP method: GET reads, POST creates or submits, PUT replaces, PATCH partially updates, DELETE removes. Every naming convention below protects that split. `POST /createUser` states the verb twice, and worse, it makes the path the place where actions live. Once that door is open the surface grows one endpoint per verb — `/createUser`, `/updateUser`, `/deactivateUser`, `/getUserByEmail` — each needing its own documentation, each opaque to anything generic sitting in the request path. With `POST /users` plus `GET /users/{id}` a reader already knows the shape of every other collection in the API. ## Plural collections The dominant convention is plural collection names with the member nested under it: `/orders` and `/orders/9f3`. The plural reads correctly for what the collection URL returns (a list) and keeps the member path a straightforward narrowing. Singular (`/order/9f3`) is defensible but consistency matters far more than the choice — an API that mixes `/users` and `/order` forces the reader to memorise instead of infer. Genuine singletons — a resource of which exactly one exists per parent — are the legitimate exception: `/users/42/avatar`, `/me/settings`. ## Casing and separators Path segments are lowercase; multi-word segments use hyphens: `/purchase-orders`, `/shipping-addresses`. Two reasons. Hosts are case-insensitive while paths are case-sensitive, so mixed case in paths creates a class of near-miss 404s that look like server bugs. And hyphens are the long-standing web convention that search engines, humans, and CLI users all read comfortably; underscores can be hidden by underlining in some UIs, and camelCase collides with the case-sensitivity trap. Query parameter *names* and JSON body fields are a separate matter — those usually follow the body's language convention (`camelCase` or `snake_case`); the hyphen rule is about path segments. ## No file extensions `/users/42.json` bakes a representation format into the identity of the resource. Format is a **representation** concern, negotiated per request with `Accept: application/json` and answered with `Content-Type`. If you need format in the URL as a pragmatic escape hatch for browsers or dumb clients, a query parameter (`?format=csv`) is less damaging than an extension, because the resource identity stays intact. ## Trailing slashes `/users` and `/users/` are, strictly speaking, different URLs, and different frameworks disagree about whether they are the same route. Pick one form (usually no trailing slash), enforce it in the router, and make the other form a `301` permanent redirect rather than a silent alias — that keeps caches, logs, and analytics from splitting one resource across two keys. ## Stability URLs are the API's public vocabulary. Avoid encoding anything volatile into a path segment: internal team names, storage technology, the current org chart, or a mutable display name. Segments that change force clients to change. Prefer identifiers that will outlive the current implementation.
- Is there ever a legitimate reason to put a verb-like word in an HTTP API path?Yes — for operations that genuinely are not create/read/update/delete on a resource, such as cancelling an order or rotating a key. The usual treatments are a state-transition sub-resource or an explicitly-marked custom method segment. The point of the noun convention is not verb-phobia; it is that CRUD-shaped work should not invent verbs it does not need.
- Singular or plural collection names — does the choice actually matter?Far less than consistency. Plural is the majority convention and reads correctly for a list endpoint, so it is the safer default in a new API. What genuinely costs teams money is mixing the two, because every endpoint then has to be looked up rather than guessed. True singletons under a parent are the one clean exception.
saying these in an interview costs you the question
- Claiming REST forbids verbs anywhere, including in custom action names
- Mixing /users and /order in one API and calling it a style preference
- Putting .json in the path and calling that content negotiation
- Treating /users and /users/ as automatically identical across all servers
- Using camelCase path segments and being surprised by case-sensitive 404s