Parameter Tree

_{Published: 28 April 2025}

Known Uses

The Parameter Tree pattern is widely used in Dutch government and energy sector APIs, especially those returning rich, nested data structures in JSON. A few examples:

• Energieonderbrekingen.nl (Dutch for energy interruptions, outages and planned maintenance by energy grid operators) provides an disruptions API, to retrieve (suspected) disruption information. The GET /disruptions/{id} endpoint returns this information as a hierarchical structure with a dedicated root node and one or more child nodes, defined as a Parameter Tree.
• The BAG API (BAG stands for Basisregistratie Adressen en Gebouwen and translates to Basic Registration of Addresses and Buildings in the Netherlands) returns a deeply nested structure with a single dedicated root node for the GET /adresseerbareobjecten/{endpointadresseerbaarObjectIdentificatie} endpoint (used to query a single addressable object using an addressable object identifier). The structure is fairly complex, with multiple levels of nesting.

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.