Nesting & Sub-Resources
You'll learn to
- -Model ownership and containment relationships as nested resource URLs, and know how deep is too deep
- -Decide when a related resource should be nested versus flattened into its own top-level collection
Real resources rarely stand alone - a comment belongs to a post, an order line belongs to an order, a cabin belongs to a ship. Nested URLs express that ownership directly: `/posts/7/comments` reads as "the comments that belong to post 7," which is both self-documenting and lets the server scope access and validation naturally.
GET /orders/501/line-items # line items belonging to order 501
POST /orders/501/line-items # add a new line item to order 501
GET /orders/501/line-items/3 # a specific line item within that orderHow Deep Is Too Deep
Nesting communicates ownership well for one or two levels, but it degrades fast beyond that - `/companies/1/departments/4/employees/9/reviews/2` is technically precise and practically unusable: every client has to know and carry the entire ancestor chain just to reference one review. The practical guideline: nest one level for a clear parent-child ownership relationship, and flatten anything deeper into its own top-level collection referenced by ID.
# Instead of this (unusable beyond ~2 levels):
GET /companies/1/departments/4/employees/9/reviews/2
# Flatten deep resources to their own top-level collection:
GET /reviews/2
# ...and let the review's own body carry the employee_id/department_id/
# company_id it needs, rather than encoding the whole ancestor chain in the URLWhen to Nest vs. When to Flatten
- -Nest when the child cannot meaningfully exist without the parent, and is almost always accessed in the parent's context - order line items rarely need a standalone top-level endpoint.
- -Flatten when the resource has its own independent identity and is frequently accessed on its own - a `/reviews/2` a user links to directly shouldn't require knowing which company and department it belongs to.
- -When in doubt, ask: "would a client ever want to fetch or reference this resource without already knowing its full ancestor chain?" If yes, flatten and reference the parent by ID in the body instead.
This mirrors the composition-vs-aggregation distinction from LLD Fundamentals' UML chapter, applied to URLs instead of class relationships: strong ownership (composition) nests naturally; independent lifecycle (aggregation) flattens naturally.
You're designing an API where comments can be attached to either a blog post or a photo. A teammate proposes `/posts/{postId}/comments/{commentId}` and `/photos/{photoId}/comments/{commentId}` as two separate nested routes. What would you flag?
"That looks fine - it clearly shows which post or photo each comment belongs to."
"The nesting works for creating and listing comments under a specific parent, but it creates two different URLs for what's conceptually the same resource type, which gets awkward the moment you need to fetch, edit, or link to a comment directly without already knowing whether it's under a post or a photo. I'd keep the nested routes for creation/listing in context, but also expose a flat `/comments/{commentId}` for direct access - the same polymorphic-association trade-off from schema design, just applied to URL structure instead of a database table."
What does nesting a resource under its parent in the URL communicate?
Design Nested Treasures in the API Design Lab's REST Foundations act.