How should you design resource URIs and naming conventions in a REST API?
Learn how to design REST API URIs: use nouns, plural collections, path hierarchy, query params for filtering, and HTTP methods for actions, with clear examples.
Expected Interview Answer
REST URIs should identify resources as nouns, use plural collection names, express hierarchy through path segments, and rely on HTTP methods rather than verbs in the URL — for example GET /users/42/orders instead of /getUserOrders?id=42.
Good URI design models resources (things), not actions: use nouns like /users and /orders, keep them lowercase and hyphenated, and let HTTP verbs (GET, POST, PUT, PATCH, DELETE) express the operation. Represent relationships with nesting (/users/42/orders), use query parameters for filtering, sorting and pagination rather than encoding them in the path, and keep URIs stable, predictable and consistent. Avoid file extensions, trailing slashes and verbs in the path so the API stays clean and self-describing.
- Predictable, self-describing endpoints
- Cleaner separation between resource and action
- Easier caching and routing
- Consistent developer experience
- URIs remain stable as the API evolves
AI Mentor Explanation
Think of how a cricket scorecard is organised: it lists teams, then players within each team, then innings within each player. You never see a column called 'go-and-fetch-the-batter'; the structure itself tells you where everything lives. REST URIs work the same way — /teams/india/players/45 mirrors that natural hierarchy of nouns, so anyone reading the path instantly knows which entity they are pointing at.
Step-by-Step Explanation
Step 1
Model resources as nouns
Name endpoints after things (/users, /orders), never actions like /getUsers or /createOrder.
Step 2
Use plural collection names
Collections are plural (/users) and a single item is addressed by id (/users/42) for consistency.
Step 3
Express hierarchy with nesting
Show relationships in the path: /users/42/orders lists orders belonging to user 42.
Step 4
Let HTTP verbs carry the action
GET reads, POST creates, PUT/PATCH updates, DELETE removes — so the URL stays a noun.
Step 5
Use query params for filtering
Put filtering, sorting and pagination in the query string: /orders?status=paid&sort=date&page=2.
Step 6
Keep names clean and stable
Lowercase, hyphenated, no file extensions or trailing slashes; avoid breaking existing URIs.
What Interviewer Expects
- Nouns not verbs in URIs
- Plural collection naming and id addressing
- Hierarchy via nested paths for relationships
- Query parameters for filter, sort and pagination
- HTTP methods carrying the operation semantics
- Consistency, lowercase and hyphenation conventions
Common Mistakes
- Putting verbs in the URL like /createUser
- Mixing singular and plural collection names
- Encoding actions or filters into the path instead of the query string
- Deeply over-nesting resources beyond one or two levels
- Using inconsistent casing or trailing slashes
Best Answer (HR Friendly)
“A REST API should name its web addresses after the things it manages, like users or orders, and keep them consistent and predictable. What you do to those things — create, read, update, delete — is decided by the request type, not by the wording of the address.”
Code Example
# Good — nouns, plural, hierarchy, verbs via method
GET /users
POST /users
GET /users/42
PATCH /users/42
DELETE /users/42
GET /users/42/orders
GET /orders?status=paid&sort=date&page=2
# Bad — verbs in path, filters in path, inconsistent
GET /getAllUsers
POST /createUser
GET /user/getOrdersById?id=42
GET /orders/paid/sortedByDate/page/2Follow-up Questions
- How deep should resource nesting go before it becomes a problem?
- When would you use query parameters versus path parameters?
- How do you version a REST API without breaking existing URIs?
- How should sub-resources versus separate top-level resources be decided?
- What is HATEOAS and how does it relate to URI design?
MCQ Practice
1. Which URI best follows REST naming conventions?
/users/42/orders uses plural nouns and hierarchy, letting the GET method express the read action.
2. Where should filtering and pagination be expressed?
Filtering, sorting and pagination belong in query parameters, e.g. /orders?status=paid&page=2, keeping the path a stable resource identifier.
3. Which is a poor URI design practice?
Verbs such as /createUser mix actions into the path; the HTTP method should carry the operation instead.
Flash Cards
Resources should be named as? — Nouns (e.g. /users, /orders), never actions or verbs in the path.
Collection naming convention? — Plural for collections (/users) and an id for a single item (/users/42).
Where do filters and pagination go? — In query parameters: /orders?status=paid&sort=date&page=2.
How is the action expressed? — Through HTTP methods — GET, POST, PUT, PATCH, DELETE — not in the URL.
How to show relationships? — Nest resources in the path: /users/42/orders for a user's orders.