Nested Resources and Relationships

Nested routes are useful when a child resource is strongly scoped by a parent relationship.

GET /users/42/orders communicates that the requested order collection belongs to user 42.

However, excessive nesting makes APIs difficult to navigate. A route such as /companies/1/departments/2/teams/4/users/9/orders/3 is usually a sign that resource identifiers should be independently addressable.

A useful rule is to nest when the parent-child relationship is central to the operation and shallow routes when resources have independent identity.

Key Takeaways
  • Use nesting to express meaningful relationships.
  • Avoid deeply nested URLs.
  • Resources with independent identity can have top-level URIs.