REST Principles
Resource Naming and URL Design
Resource naming defines the structural hierarchy of your data interface using nouns that represent objects rather than actions. This design is critical for maintaining predictable, discoverable APIs that minimize cognitive load for developers integrating with your system. Use these naming principles whenever you are defining a new data entity or expanding existing API endpoints to ensure long-term scalability and consistency.
Using Nouns Over Verbs
In REST, a resource is an object with data and behavior, not an operation. When we design URIs, we represent 'things'—like users, products, or invoices—rather than 'actions' like 'create' or 'delete'. Using nouns makes the API interface intuitive because it maps directly to your data model. If you use verbs in your URL, you are essentially creating an RPC (Remote Procedure Call) style interface rather than a resource-based one, which complicates caching and standard HTTP method usage. By focusing on nouns, you encourage the use of standard HTTP verbs (GET, POST, PUT, DELETE) to define the action. This separation of concerns is fundamental to the REST architectural style, ensuring that the URL identifies the resource uniquely, while the HTTP method defines what you want to do with that specific resource, leading to a clean, highly readable, and easily maintainable codebase for all stakeholders involved.
# Correct: Noun usage
# GET /users/123
# Correct: Noun usage
# POST /users
# Incorrect: Verb usage
# GET /getUser?id=123Maintaining Hierarchical Relationships
Resource naming should reflect the logical hierarchy of data within your application. When an object is a sub-component of another, it is natural to represent this through nested paths in the URI structure. This pattern tells the client that the child resource is scoped to the parent. For instance, an order belongs to a specific user, so nesting it makes the relationship clear and allows for intuitive navigation. However, deeper nesting than two levels can lead to long, cumbersome URLs that are difficult to manage. If you find yourself nesting three or four levels deep, consider whether the sub-resource needs to be treated as a top-level entity instead. This approach helps maintain a balance between clarity and complexity, providing a logical map of the system's structure that allows developers to traverse the API naturally without requiring extensive documentation to understand where specific data points are located.
# Hierarchical resource paths
# Get all orders for a specific user
path = "/users/101/orders"
# Get a specific order within that user's profile
path = "/users/101/orders/550"Consistent Casing and Delimiters
Consistency is the most vital aspect of URI design. Whether you choose hyphens or underscores, the most important rule is to be uniform across your entire API implementation. Hyphens are generally preferred in industry standards for web addresses because they are easier to read and improve searchability compared to underscores, which can be hidden by underlining in browsers. Regardless of the choice, avoid mixing casing styles like camelCase or PascalCase, as these can lead to confusion and interoperability issues. A unified naming convention signals to the developer that the API is professionally maintained and decreases the likelihood of errors when building client-side integrations. Establishing this convention early in the design process prevents the accumulation of technical debt, where different teams might implement different patterns, ultimately leading to a fragmented and frustrating experience for those consuming the service who expect a predictable interaction pattern across every endpoint.
# Preferred: Hyphens for readability
# /customer-profiles/premium-users
# Discouraged: Inconsistent casing
# /customerProfiles/Premium_UsersPluralization Strategies
There is a long-standing debate regarding whether to use singular or plural nouns for resource collections. Following the REST philosophy of treating an endpoint as a collection of resources, pluralization is the widely accepted industry standard. For example, using '/products' as the endpoint to retrieve a list of products makes logical sense because the result returned is a set. When a specific ID is added to that path, like '/products/42', it correctly identifies a single instance within that collection. This consistency makes the API predictable; a developer knows that '/items' is for the list, and appending an ID is for the individual item. Mixing singular and plural creates unnecessary ambiguity, forcing the developer to guess whether to query '/user' or '/users'. By adopting a strict 'always plural' policy for collections, you simplify the developer experience and make the API structure feel robust and standard across every single endpoint.
# Consistent pluralization
# Base collection endpoint
collection = "/products"
# Individual resource endpoint
resource = "/products/42"Handling Query Parameters for Filtering
While path segments define the specific resource, query parameters are the correct tool for filtering, sorting, and pagination. A common mistake is to create new path segments for filtering, such as '/products/active' or '/products/sorted-by-price'. This bloats your API surface area and forces the developer to learn new, non-standard paths. Instead, keep the resource path clean and use query string parameters to modify the representation of the collection. This allows for flexible combinations, such as filtering and sorting at the same time, without defining an explosion of URI combinations. Query parameters are inherently optional and represent a view or a subset of the resource, which aligns perfectly with the goal of keeping the core URI stable. This design pattern ensures that the underlying resource identification remains constant while providing the client the necessary tools to request exactly the slice of data they need for their specific business logic requirements.
# Using query parameters for flexibility
# Filtering: /products?status=active
# Sorting: /products?sort=price_desc
# Combined: /products?status=active&sort=price_descKey points
- Always represent resources as nouns rather than actions.
- Use HTTP methods to define the operation performed on a resource.
- Structure paths hierarchically to reflect relationships between entities.
- Maintain consistent casing, preferably using hyphens for delimiters.
- Adopt a plural-first approach for all resource collection endpoints.
- Reserve path segments for identification and query parameters for filtering.
- Avoid deep URI nesting to maintain simplicity and prevent complexity.
- Design for predictability so that developers can infer resource paths.
Common mistakes
- Mistake: Using verbs in URLs (e.g., /getUsers). Why it's wrong: REST is resource-oriented, and HTTP methods already convey intent. Fix: Use nouns describing the resource, e.g., /users.
- Mistake: Using singular nouns for collections (e.g., /user). Why it's wrong: Collections represent sets of resources, and plural nouns provide better semantic clarity. Fix: Use plural nouns, e.g., /users.
- Mistake: Including API versioning in the query string (e.g., /users?v=2). Why it's wrong: Versioning should be stable and easily cacheable at the resource path level. Fix: Use a URI path prefix, e.g., /v2/users.
- Mistake: Exposing internal database schema details. Why it's wrong: It creates tight coupling between the implementation and the contract, making it difficult to refactor. Fix: Use domain-specific resource names that reflect the business model.
- Mistake: Relying on overly deep nesting (e.g., /users/1/orders/5/items/12). Why it's wrong: It creates brittle URLs and makes the API hard to navigate. Fix: Keep URLs flat and use query parameters for filtering or secondary associations.
Interview questions
What is the fundamental difference between using plural nouns and singular nouns when designing REST resource URIs?
In REST API design, it is standard practice to use plural nouns for resource identifiers, such as '/users' instead of '/user'. The rationale is that a URI represents a collection of resources. When you access '/users', you are logically pointing to the entire set. If you need a specific item, you append the identifier, like '/users/123'. Using plurals provides consistency and predictability, which makes the API easier for developers to navigate, as they intuitively understand that a base path represents a category of data objects rather than a single instance.
Why should we avoid including verbs in our RESTful resource paths?
REST is a resource-oriented architecture, not a remote procedure call mechanism. Paths should represent the 'what'—the data entities—rather than the 'how'—the actions. We rely on the HTTP methods (GET, POST, PUT, DELETE) to define the operation. For example, use 'GET /orders' to retrieve orders instead of '/getOrders'. Including verbs leads to bloated, non-standard URIs that ignore the semantic power of the HTTP protocol. By focusing on nouns, you keep the URI space clean, intuitive, and properly aligned with REST principles, ensuring that clients interact with resources using standard HTTP verbs.
How do you handle hierarchical relationships in URIs, and what is the maximum depth one should aim for?
Hierarchical relationships are best represented by nesting child resources under parent resources, such as '/authors/5/books'. This structure clearly defines the ownership or association between data entities. However, you should generally keep URI depth to no more than two or three levels, like '/authors/5/books/10'. If you go deeper, the URIs become brittle, hard to read, and difficult to manage. If a resource has many relationships, it is often better to flatten the URI structure and use query parameters to filter by parent ID, keeping the path simple and maintainable.
Compare using query parameters versus sub-resources for filtering and sorting.
Sub-resources are best for defining specific data relationships, such as '/users/1/orders'. Conversely, query parameters are the correct tool for filtering, sorting, and pagination of an existing collection. For example, 'GET /users?status=active&sort=name' is far superior to creating custom paths like '/users/active/sorted'. Using query parameters keeps the resource URI stable and avoids 'path explosion,' where you would otherwise need countless endpoint variations. Always use sub-resources for identity and association, but reserve query parameters for the presentation and refinement of that data set.
What are the risks of exposing internal database IDs in your public-facing resource URIs, and what is a common alternative?
Exposing internal database primary keys, like auto-incrementing integers, in URIs can be a security risk. It allows malicious actors to guess valid resource IDs or estimate the volume of data in your system. To mitigate this, many designers use Universally Unique Identifiers (UUIDs) or URL-friendly slugs. For example, using '/products/a1b2c3d4-e5f6-...' instead of '/products/12' obscures the internal structure of your database. This approach decouples your public API contract from your internal data storage, allowing you to refactor your backend without breaking public links or leaking sensitive business intelligence about your record counts.
Explain the design strategy for an API that requires managing a singleton resource versus a collection.
A singleton resource represents exactly one instance that doesn't have a parent ID, such as a user profile. In this case, you might design the URI as '/profile'. For a collection, you use plural nouns like '/profiles'. The challenge arises in 'sub-singleton' cases, such as a user’s single settings object, which is accessed via '/users/1/settings'. The design strategy here is to maintain a consistent pattern: the URI must point to a stable resource identifier. If an object is unique to a context, omit the ID for that specific segment of the path to keep the API design clean and semantically accurate.
Check yourself
1. Which URL design best represents the principle of resource-based naming for a specific comment belonging to a post?
- A./getComment?id=123
- B./posts/5/comments/123
- C./retrievePostComment/5/123
- D./comments/123
Show answer
B. /posts/5/comments/123
/posts/5/comments/123 uses nouns and hierarchical nesting, which correctly identifies a resource within a collection. The first option uses a verb, the third uses a verb-noun hybrid, and the fourth loses the context of the parent post.
2. How should a search feature that filters users by 'active' status be represented?
- A./users/active
- B./users?status=active
- C./findActiveUsers
- D./users/search/active
Show answer
B. /users?status=active
Query parameters are designed for filtering and sorting collections without changing the resource identifier. The other options treat 'active' as a sub-resource or use verbs, which violates REST constraints.
3. When designing a URL for a resource collection, which practice is most consistent with REST principles?
- A.Always use plural nouns to indicate a collection
- B.Use singular nouns to distinguish individual resources from the set
- C.Include the HTTP method name at the end of the URL
- D.Use kebab-case for some segments and snake_case for others
Show answer
A. Always use plural nouns to indicate a collection
Plural nouns are standard for collections. Using singular nouns for collections is confusing, including methods in URLs is redundant, and inconsistent casing makes an API unpredictable.
4. What is the primary architectural benefit of maintaining flat URL structures?
- A.It forces the client to download the entire database schema
- B.It minimizes API coupling to the hierarchical storage implementation
- C.It allows the server to change resource associations without changing endpoints
- D.It ensures that all queries return the same amount of data
Show answer
B. It minimizes API coupling to the hierarchical storage implementation
Flat structures prevent the API contract from being strictly tied to deeply nested database relationships, allowing for internal refactoring. The other options are incorrect interpretations of API goals.
5. Which of the following is the most standard approach to handling pagination in an API?
- A./products/page/2
- B./products/limit/10/offset/20
- C./products?page=2&size=10
- D./products?next=2
Show answer
C. /products?page=2&size=10
Pagination should be handled through query parameters, as it represents a view state of the collection rather than a new resource. The other options incorrectly embed navigation metadata into the resource path.