Course contentsShow
← Software Engineering
Lesson 776 of 1,93324. REST API DesignFree lesson

Designing Resource Hierarchies

Understand how to structure nested and related resources using parent-child relationships in URLs.

Designing Resource Hierarchies

You'll learn how to structure nested and related resources using parent-child relationships in URLs to reflect natural data dependencies.

The Core Idea

Not all resources stand alone. Often, resources naturally belong to other resources: comments belong to posts, line items belong to orders, chapters belong to books. A well-designed REST API mirrors these real-world relationships through hierarchical URLs that show ownership and context.

Think of it like a filing system: you wouldn't throw all papers in one drawer. You'd organize folders by client, then subfolders by project, then documents within each project. Resource hierarchies work the same way—they give structure and meaning to your API.

How Hierarchies Work

Use forward slashes (/) to indicate parent-child relationships:

  • /users/42/orders — all orders belonging to user 42
  • /orders/789/items — line items within order 789
  • /courses/CS101/students — students enrolled in CS101

The pattern reads naturally left-to-right: "In the collection of users, find user 42, then look at their orders."

When to Use Hierarchies

Use nested URLs when:

  • The child resource cannot meaningfully exist without its parent (a comment without its post)
  • You need to scope operations to a specific parent (get only this user's posts)
  • The relationship is clear and stable in your domain

Avoid deep nesting beyond 2-3 levels—/a/1/b/2/c/3/d/4 becomes unwieldy. If a resource can be accessed independently or belongs to multiple parents, give it a top-level collection instead (e.g., /products rather than nested under every category).

Key Takeaway:
Resource hierarchies use URL paths to express parent-child ownership, making APIs intuitive and aligned with how data naturally relates in your domain.