REST URI Design Principles
Fast recall
Quick revision
Core answer
Interview-ready guide
Interview answer
A good REST URI identifies a resource, while the HTTP method states the requested action. /orders identifies the order collection and /orders/42 identifies one order. The client then uses GET, POST, or DELETE with that address. This is why GET /orders/42 is clearer than GET /getOrder/42: the method already carries the verb.
Use one consistent pattern for collections and individual resources. GET /orders reads the collection, POST /orders submits a new order to it, GET /orders/42 reads one member, and DELETE /orders/42 requests removal of that member's URI association. The same resource names remain useful across operations, so clients do not have to learn a new action-shaped path for each controller method.
Nesting is useful when the parent supplies real context. /orders/42/items clearly means the item collection belonging to order 42. If item 9 also has an independent life, give it a direct address such as /items/9. Paths such as /customers/7/orders/42/items/9/notes repeat relationships, couple clients to the current model, and make route changes harder.
Collection controls usually fit the query component: /orders?status=paid&sort=-createdAt&limit=20 identifies a paid, newest-first view of orders. The query string is still part of the target URI; it is not merely optional decoration. Document allowed filters, sort fields, defaults, and limits so two clients interpret the same URI in the same way.
Public URIs should remain stable when Java class names, controller methods, or database tables change. Avoid exposing names such as /tbl_orders or file extensions that turn implementation details into a client contract. Plural nouns, lowercase paths, and hyphens are helpful conventions, not rules imposed by REST. The real goal is a clear resource model and one naming style that stays predictable across the API.
REST URI Design Principles
Direct Answer
A good REST API URI is a stable, readable identifier for a resource, while the HTTP method expresses the requested action. Use nouns for collections and individual resources, model genuine relationships with shallow nesting, keep naming consistent, and avoid exposing database or controller implementation details.
Deep Dive & Architecture
A route becomes simple when the underlying resource model is clear. Begin with the things that have identity: customers, orders, products, and payments. A collection URI identifies a set, while a member URI identifies one resource within that set. The same URI can support different method semantics; the path does not need a verb for each operation.
Containment and association are different. /orders/42/items is useful when the client is asking for the item collection in the context of one order. An item that can be addressed, updated, or referenced independently should also have a stable member URI. Deep nesting makes authorization rules, route changes, and client code harder without adding meaning.
The query component changes how a resource is selected or represented. Filters such as status=paid, sorting such as sort=-createdAt, field selection, and pagination are common query controls. They should have documented defaults and allowed values. A query URI is still a resource identifier and can be linked or cached according to normal HTTP rules.
There is no REST specification that requires plural nouns or lowercase paths. Those are design conventions. The architectural requirement is a uniform interface in which resources are identified and messages are self-descriptive. Consistency matters because clients learn a vocabulary; blindly following a naming rule cannot repair a confused resource model.
Code Example
GET /orders?status=paid&limit=20 HTTP/1.1
Host: api.example.com
Accept: application/json
POST /orders/42/items HTTP/1.1
Host: api.example.com
Content-Type: application/json
{"productId": "P-9", "quantity": 2}
The first request selects a filtered collection representation. The second submits a new member to the item collection owned by order 42; neither route repeats the action as a path verb.
Check your understanding
Answer these without looking back at the article.
- When is nested URI design useful, and when is it too deep?
- Should filtering and sorting appear in the path or query string?
- Why should a public URI not expose database table names?
Looking for a structured roadmap?
Every module on this page is also part of the full Java backend interview track.