Nesting & Sub-Resources
You'll learn to
- -Model ownership and containment as nested resource URLs, and know how deep is too deep
- -Decide when a related resource should be nested versus flattened into its own collection
- -Combine the two: nest to list and create, flatten to address by id
- -Enforce that a child really belongs to the parent named in the URL
Tip: the highlighter is on - just select any text below to mark it. Use the highlighter button up top to change color or turn it off. Highlights are saved on this device only. Log in to save them to your account instead.
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.
An Analogy: Addresses and ID Numbers
A postal address, country, city, street, house number, tells you where someone lives and how the places relate. But you would not use it to refer to a person in a database: it is long, it changes when they move, and you need every part to find them. A passport number is short and stands on its own. Good API design uses both ideas: nested URLs for relationships, and a short unique id for anything that deserves to be addressed directly.
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.
Hybrid: Nest to Create and List, Flatten to Address
In practice the best designs mix both. Use the nested route where the parent gives context, to list and to create, and give every item a globally unique id so it can also be reached directly:
GET /orders/501/line-items # list the items of order 501
POST /orders/501/line-items # add an item to order 501
GET /line-items/3 # fetch one item directly, by its unique idThe same idea answers the question of a resource that can belong to different parents. If comments may be attached to a post or to a photo, do not write /posts/{id}/comments/{id} and /photos/{id}/comments/{id} as two parallel designs. Create one comments resource with a reference to what it is about, {"target": {"type": "photo", "id": "p9"}, "text": "Lovely"}, and offer the nested list routes as convenient views over it. You get one set of rules to maintain instead of two.
A Check That Nesting Makes Easy to Forget
With a nested URL such as GET /orders/501/line-items/3, the server must confirm that line item 3 really belongs to order 501. If it looks up item 3 by id alone and returns it, then a user who owns order 501 can read any item in the system by changing the order number in the URL, a vulnerability known as an insecure direct object reference. The correct behavior is to look up the item within that order, and answer 404 if it is not found there.
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.
Discussion0
Join the Discussion
Sign in to leave comments, reply to others, or like insights.
No comments yet. Be the first to start the thread!