Resource Hierarchies and Nested URLs

When designing URLs, it is natural to start with the relationships in your domain: an order contains lines, a customer places orders, and a warehouse ships them. It can be tempting to turn all those relationships into one long URL. But an address that includes every related object forces callers to know details they may not need and can become unstable when those details change.

Resource hierarchies help when a parent supplies meaningful identity or scope.

This chapter explains how to choose that hierarchy, combine nested collections with direct item URLs, and define the behavior of missing, moved, or inaccessible children. The examples use a fictional bookstore API.