Parameter Tree

_{Published: 28 April 2025}

Known Uses

This atterns is frequently used. Some industry standards (e.g., CIM, OASIS UBL) allow for an excessive number of nesting levels, causing overhead and introducing the risk that unnecessary structural information is exchanged between the API client and provider.

Discussion Input

In the API design community, there is ongoing debate about the appropriate level of nesting in URIs. Some argue that deep hierarchies (e.g., /customers/1/orders/5/products) help reduce API chattiness, while others advocate for simpler, more maintainable URIs.

For example, instead of using /customers/1/orders/5/products, a more structured approach would be:

• /customers/1/orders – to retrieve all orders for a specific customer
• /orders/5/products – to fetch the products in a particular order

In general, minimizing deeply nested parameter tree structures in message transfers is considered best practice (as highlighted in the book on page 154 and on https://api-patterns.org/patterns/structure/representationElements/ParameterTree). This aligns with the Law of Demeter, which promotes low coupling – a key principle in designing maintainable and robust APIs. A well-designed API should focus on delivering only the data the client needs, rather than exposing internal data structures as unnecesary overhead (encapsulation).

These best practices are reflected in various API design guidelines:

• DSO API Guidelines: Advise limiting sub-resource nesting to three levels to maintain clarity and ensure URLs remain within acceptable length limits
• Zalando: Recommends a maximum of three levels of sub-resources to prevent excessive complexity and long URLs

Recommended Reading

• Principles of Web API Design (Higginbotham 2021): Nesting dependent resources is a useful design option but should be used only when it improves the usability of the API.