Resource Naming and URI Design Best Practices

In the world of RESTful API development, the Uniform Resource Identifier (URI) is the primary way consumers interact with your service. A well-designed URI is intuitive, easy to remember, and follows a logical structure. Think of a URI as the "address" of a specific resource. Just as a physical address helps a mail carrier find a house, a URI helps a developer find a specific piece of data or functionality within your system.

The Fundamental Rule: Use Nouns, Not Verbs

REST stands for Representational State Transfer. It is resource-oriented, not action-oriented. Therefore, your URIs should always represent resources (nouns) rather than actions (verbs). The action is determined by the HTTP method (GET, POST, PUT, DELETE) used on that resource.

• Bad Practice: /getUsers, /createOrder, /deleteProduct/123
• Good Practice: /users, /orders, /products/123

Use Plural Nouns for Collections

To maintain consistency across your API, it is a standard industry practice to use plural nouns for all resources. This makes it clear that the base endpoint represents a collection, while a specific ID points to a single item within that collection.

• /customers (Refers to the collection of all customers)
• /customers/5 (Refers to a specific customer with ID 5)

Representing Hierarchy and Relationships

When resources have a parent-child relationship, the URI structure should reflect that hierarchy. Use the forward slash (/) to indicate sub-resources.

/authors/102/books
/authors/102/books/45
    

In the example above, we are accessing the book with ID 45 that belongs specifically to the author with ID 102. This structure makes the relationship between authors and books immediately obvious to the API consumer.

URI Design Flowchart

Understanding how to map a request to a URI can be visualized through this logical flow:

[Start]
  |
  V
[Identify the Resource] ----> (Is it a Collection?) ----> /plural-noun
  |                                  |
  |                                  V
  |                          (Is it an Item?) ----------> /plural-noun/{id}
  |                                  |
  V                                  V
[Check Relationships] ------> (Does it have children?) -> /plural-noun/{id}/sub-resource
  |
  V
[Apply Filters] ------------> (Need to sort/filter?) ---> /plural-noun?sort=desc
    

Case Sensitivity and Formatting

URIs are technically case-sensitive (except for the scheme and host). To avoid confusion and improve readability, follow these formatting rules:

• Use Lowercase: Always use lowercase letters in your URI paths. /api/user-profiles is better than /api/UserProfiles.
• Use Kebab-case: If a resource name consists of multiple words, use a hyphen (-) to separate them. This is known as kebab-case. Example: /shipping-addresses.
• Avoid Underscores: Underscores (_) can sometimes be hidden by underlines in browser links or documentation, making them hard to see.

Query Parameters for Filtering and Sorting

Do not create new URI paths for filtering, searching, or sorting. Instead, use query parameters. Query parameters are the part of the URI that comes after the question mark (?).

• Filtering: /products?category=electronics
• Sorting: /users?sort=last_name
• Pagination: /orders?page=2&limit=50

Common Mistakes to Avoid

• Trailing Slashes: Do not use a trailing slash at the end of a URI. /users/ is different from /users in some systems and can lead to 404 errors.
• File Extensions: Avoid using extensions like /users.json or /users.xml. Use the Accept header in the HTTP request to negotiate the content type.
• Deep Nesting: Avoid nesting resources deeper than two or three levels. /users/1/posts/5/comments/10/replies is too complex. Use query parameters or separate endpoints instead.

Real-World Use Cases

E-commerce Platform

An e-commerce API might use the following structure: /categories/appliances/products to list all appliances. To view a specific product, the URI would be /products/sku-9921.

Social Media API

To fetch the followers of a specific user, the URI design would be: /users/john_doe/followers. This clearly defines "followers" as a sub-resource of a specific "user".

Interview Notes for Developers

• Question: Why should we use nouns instead of verbs in REST URIs?
• Answer: REST is resource-based. The HTTP methods (GET, POST, etc.) already provide the "verb" or action. Using verbs in the URI makes it redundant and moves the design toward RPC (Remote Procedure Call) rather than REST.
• Question: How do you handle versioning in URIs?
• Answer: While there are multiple ways, a common practice is to include the version at the start of the path, such as /v1/customers.
• Question: What is the difference between a Path Parameter and a Query Parameter?
• Answer: Path parameters (/users/123) are used to identify a specific resource. Query parameters (/users?status=active) are used to filter, sort, or paginate that resource.

Summary

Effective URI design is a cornerstone of a high-quality RESTful API. By using plural nouns, maintaining a logical hierarchy, and utilizing query parameters for non-identifying operations, you create an API that is self-documenting and developer-friendly. Remember to keep URIs lowercase, use kebab-case for multi-word resources, and avoid including actions or file extensions in the path. Following these best practices ensures your API remains scalable and consistent as it grows.