RESTful URI Design for Resources

1. What is a Resource?

In REST, everything is a resource. A resource is any piece of information that can be named and accessed—a user, an order, a product, or even a collection of products. The URI is the unique identifier for that resource.

Let's look at the anatomy of a typical endpoint URI to see where resources fit in.

As you can see, the path of the URI (e.g., /employees/{emp-id}) is responsible for identifying the resource.

To understand how to structure this path, it's crucial to distinguish between two types of resources.

To summarize:

• Collection Resource: Represents a list or collection of items. For example, /customers represents all customers.
• Singleton (or Document) Resource: Represents a single, specific item. For example, /customers/123 represents the customer with the ID 123.

2. The Golden Rule: URIs are for Nouns, Not Verbs

The single most important principle of RESTful URI design is that URIs identify resources (nouns), while HTTP methods (GET, POST, PUT, DELETE) specify the action (verb) to be performed on that resource.

Your URI should describe the "what," not the "how."

Let's reinforce this with some clear examples from the Microsoft Azure documentation on API design.

Here's the takeaway:

• Bad: /getUsers, /createUser, /deleteUser/123
• Good: Use the single resource path /users and combine it with different HTTP methods:
  • GET /users — Get a list of all users.
  • POST /users — Create a new user.
  • GET /users/123 — Get the user with ID 123.
  • DELETE /users/123 — Delete the user with ID 123.

This separation makes your API logical and predictable. Once a developer knows the URI for your "users" resource, they can infer how to perform all standard operations on it.

3. Core Naming Conventions

Beyond the "nouns, not verbs" rule, several conventions help create consistent and intuitive APIs.

Use Plural Nouns for Collections

A widely adopted convention is to use plural nouns for collection resources. This reads naturally and aligns with the concept that the URI points to a collection of items.

• GET /users — Retrieves the collection of all users.
• GET /users/42 — Retrieves the single user with ID 42 from the users collection.

Indicate Hierarchy with Forward Slashes

You can represent relationships between resources using the forward slash /. For instance, if a User has many Orders, you can model this relationship in the URI.

• GET /users/42/orders — Retrieves all orders belonging to the user with ID 42.
• GET /users/42/orders/3 — Retrieves order #3 that belongs to user #42.

Practical Tip: Avoid Deeply Nested URIs

While nesting is useful, it can quickly become cumbersome. A URI like /customers/1/orders/99/products/4 is complex, hard to read, and brittle if resource relationships change.

A good rule of thumb is to avoid nesting more than one or two levels deep.

Instead of /customers/1/orders/99/products, you could provide:

1. /orders/99 to get the order details.
2. The response for that order could then contain a link or information to fetch its products, perhaps via /orders/99/products or even /products?orderId=99.

4. URI Formatting and Style Guide

To ensure maximum readability and prevent technical issues, follow these simple formatting rules.

Here is a summary of the key style rules:

• Use lowercase letters: URI paths can be case-sensitive. Using lowercase consistently avoids confusion.
  • Good: /users/123/orders
  • Avoid: /Users/123/Orders
• Use hyphens (-) to separate words: Hyphens improve the readability of long resource names.
  • Good: /order-items
  • Avoid: /orderitems or /order_items (underscores can be hard to see).
• Do not use a trailing forward slash (/): A slash at the end of a URI path adds no semantic value.
  • Good: /users
  • Avoid: /users/
• Do not use file extensions: The server should determine the content format (e.g., JSON, XML) using the Accept header in the request, not by putting .json in the URI.
  • Good: /users/123
  • Avoid: /users/123.json

5. Connecting URIs to Actions: A Preview

Let's bring everything together. The URI identifies the noun, and the HTTP method provides the verb. This table perfectly illustrates how different actions are performed on the same set of resources.

Looking at this table, you can see the power of this design. By defining just two URI patterns, /users and /users/{id}, you have established a predictable contract for a whole range of operations. This is the essence of a well-designed RESTful API.

Conclusion

Great job! You've just learned the fundamental principles for designing clean, predictable, and professional RESTful URIs. This is a crucial skill that makes your APIs easier for others to understand and consume.

Key Takeaways:

• URIs identify resources (nouns), not actions (verbs).
• Use plural nouns for collection resources (e.g., /users).
• Use forward slashes (/) to represent hierarchical relationships, but avoid nesting too deeply.
• For formatting, stick to lowercase letters and use hyphens (-) to separate words.
• The HTTP method (GET, POST, etc.) determines the action to be performed on the resource identified by the URI.

What's Next?

Now that we've mastered how to name our resources, the next logical step is to dive deeper into the "verbs." In our next lesson, we will explore how to select appropriate HTTP methods (GET, POST, PUT, DELETE, PATCH) based on their specific properties, such as idempotency and safety. This will complete your understanding of how to structure basic REST interactions.