Designing RESTful API Endpoints

The Foundation: Resources as Nouns

In the world of REST, everything revolves around the concept of a resource. A resource is simply a representation of any "thing" or entity your system manages—a user, a product, an order, or a blog post. The URI is the unique identifier for that resource.

The single most important rule in RESTful URI design is: URIs identify resources (nouns), not actions (verbs). The action is communicated by the HTTP method we covered previously.

Let's look at the anatomy of a typical endpoint URI.

Our focus today is on the resource and parameter parts of this URI.

The following article from restfulapi.net provides an excellent foundation for thinking about resources.

As the article states, a resource can be a collection (e.g., /customers) or a singleton (e.g., /customers/{id}). This is a core concept. A common convention, and one you should follow in interviews, is to always use plural nouns for your resource collections. This keeps your API paths consistent and predictable.

For a great interview-centric perspective on this, the following video by a Meta Staff Engineer is invaluable.

To summarize the key rule:

• DON'T: POST /createUser
• DO: POST /users

The URI identifies the collection of users, and the POST method clearly signals the intent to create a new one within that collection.

Structuring URIs: Hierarchy and Readability

Once you've identified your noun-based resources, you need to structure them in a clear, hierarchical way. The principles for this are straightforward and focus on predictability and ease of use.

Let's break down these principles.

1. Use Forward Slashes for Hierarchy

The / character indicates a hierarchical relationship. You can use this to navigate from a collection to a specific instance or to a related sub-collection.

• GET /users — Retrieves a list of all users.
• GET /users/123 — Retrieves a single user with ID 123.
• GET /users/123/orders — Retrieves a list of all orders belonging to user 123.
• GET /users/123/orders/456 — Retrieves a single order with ID 456 belonging to user 123.

While nesting is powerful, it's wise to follow the principle from the image above: Keep hierarchy shallow. Generally, nesting more than two or three levels deep (/resource/id/sub-resource) can lead to long, unwieldy URIs and may indicate that your resource model is too complex.

2. Use Hyphens for Readability

When a resource name contains multiple words, use hyphens (-) to separate them. Avoid underscores (_) as they can be less visible, and avoid camelCase (multiWord) as it's inconsistent with the DNS host naming convention.

• DON'T: /blog_posts or /blogPosts
• DO: /blog-posts

3. Use Lowercase Letters

RFC 3986 specifies that URI paths are case-sensitive. To avoid confusion and potential errors, the established convention is to use only lowercase letters in your URI paths.

• DON'T: /Users/123/Orders
• DO: /users/123/orders

4. Avoid Trailing Slashes and File Extensions

A trailing slash (/) adds no semantic value. Is /users/ a different resource from /users? To avoid ambiguity, the convention is to omit it.

Similarly, don't include file extensions like .json or .xml in your URIs. The format of the data should be determined through content negotiation using HTTP headers (e.g., the Accept header). The URI should represent the resource itself, not its format.

• DON'T: /users/123.json
• DO: GET /users/123 (with an Accept: application/json header)

The following short video provides a great summary of these formatting best practices, framing them for an interview context.

For a more detailed written reference on these conventions, you can consult the following article.

Path Parameters vs. Query Parameters: A Critical Distinction

A common point of confusion—and thus a great interview topic—is when to put a parameter in the URI path versus in the query string. The rule is simple and logical.

As the video explains:

• Path Parameters are used to identify a specific resource or resources. They are not optional and form a core part of the resource's identity.

  • Example: GET /users/{userId} — The userId is required to identify the user.
  • Example: GET /users/{userId}/orders/{orderId} — Both IDs are required.

• Query Parameters are used for optional filtering, sorting, or paginating a collection of resources. They refine the request but don't change the fundamental resource being accessed.

  • Example: GET /orders?status=shipped&sort=date_desc — Here, we are still accessing the orders collection, but we are filtering and sorting the results.
  • Example: GET /products?category=electronics — This filters the products collection.

Think of it this way: the path gets you to the "aisle" in the store (the resource collection), while the query parameters help you find specific items on the shelves in that aisle.

Putting It All Together

Let's combine everything we've learned in this lesson and the previous one. Imagine you're in an interview and asked to design the API endpoints for managing articles in a blogging platform.

Here is what a well-designed set of RESTful endpoints would look like:

Notice how all these endpoints adhere to the principles:

• Nouns: articles, comments.
• Plural: All collections are plural.
• Hierarchy: /articles/{articleId}/comments shows a clear relationship.
• Formatting: Lowercase, no verbs, no file extensions.
• Parameters: Path parameters for IDs ({articleId}), query parameters for filtering (?author-id=123).

Conclusion

In this lesson, we've built upon our knowledge of HTTP methods to design the structure of RESTful URIs. You now have a complete framework for defining the "what" (resources) and the "how" (HTTP methods) of an API. A developer who sees an endpoint like GET /users/123/orders should immediately understand its purpose without needing extensive documentation, and that is the hallmark of a great API design.

Key Takeaways:

• Resources are Nouns: URIs should represent entities (/users), not actions (/getUsers).
• Use Plural Nouns: Conventionally, collections are named with plural nouns for consistency (e.g., /articles, not /article).
• Hierarchy with Slashes: Use / to show relationships, but keep nesting shallow (2-3 levels max).
• Consistent Formatting: Use lowercase letters and hyphens for multi-word resources. Avoid trailing slashes and file extensions.
• Path vs. Query Parameters: Use path parameters for required identifiers (/articles/{id}) and query parameters for optional filtering, sorting, or pagination (/articles?status=published).

In our next lesson, we will complete the request-response cycle by learning how to select appropriate HTTP status codes for success, client error, and server error scenarios. This will enable you to design APIs that communicate their results clearly and effectively to clients.