Pattern Adoption Stories from Readers: Dutch Government & Energy Sector (4/5)

This pattern adoption story was contributed by Ton Donker, Ruben Haasjes and their readers group. It covers the 21 patterns presented as API Design Pattern of the Week on LinkedIn and Medium as well as other patterns from our book. This page features part 4 of 5 (part 1, part 2, part 3, part 5).

Atomic Parameter

Known Uses

The Atomic Parameter is a fundamental pattern that defines a single header, query, path parameter, or body element when HTTP is used as a message exchange protocol. It is, of course, widely used. A few examples in the Dutch government sector are:

The DSO API register (DSO: Environment and Planning Act of the Netherlands) offers APIs, such as the Spatial Plans API, to retrieve (parts of) spatial plans. Via GET/plannen/{planId} a single plan is requested. The path parameter ‘planId’ qualifies as an Atomic Parameter. The Atomic Parameter ‘type’ as one of the simple, unstructured response attributes has a specific value range, made explicit in the schema definition.
The Environmental Document Download API on the DSO API register enables downloading a regulation version of an environmental document containing the legal text as a ZIP file. An example of a request to download the legally binding version of an environmental plan (from the fictional municipality with BG code gm9999) is: POST /aanvraag with ‘regelingId’ an Atomic Parameter into the body of the POST message: {"regelingId": "/akn/nl/act/gm9999/2022/omgevingsplan"}. The response to this POST request is a ‘202’ with a single unique id as Atomic Parameter in the response: {"verzoekIdentificatie": "123e4567-e89b-12d3-a456-426614174000"}.

The book describes the Atomic Parameter pattern as a form of “scalar representation”. This refers to representing a value as a single, self-contained unit rather than a complex or structured data type. In API design, scalar representation typically means using primitive types (such as string, number, or boolean) instead of structured or nested objects.

Discussion Input

As simple as they are, Atomic Parameter raise interesting and non-trivial design discussions.

For instance, there has been ongoing debate about whether adding a new enum value in API responses is considered a breaking change, particularly when using atomic parameters with a set of values. According to Otto’s API guidelines, adding a new enum value in the response is a breaking change (see Otto’s API guidelines). However, others argue that if clients follow Postel’s Law (be liberal in what you accept the robustness principle), they can simply ignore unknown values, thus avoiding this compatibility issue.

Zalando (and OTTO) have proposed the x-extensible-enum tagging approach. This allows for the specification of an open-ended list of values through the x-extensible-enum property. Clients must be prepared for new enum values to be added without requiring a new version of the API. This approach clearly signals the possibility of extending enum values without breaking the contract. The x-extensible concept has also been discussed within the OpenAPI Specification community (see OpenAPI Specification Issue).

If the list of enum values is expected to change frequently (e.g., product categories) or if the values are user-configurable (e.g., custom tags), it might be better to avoid enums in API contracts altogether.

A good practice for using Enums in API Contracts is to expose enums as strings instead of integers. In our sector, we have temporarily avoided using enums in API descriptions and are currently exploring the use of the x-extensible-enum property.

Atomic Parameter List

Known Uses

Two known usess of Atomic Parameter List are:

CloudEvents is a vendor-neutral specification for defining the format of event metadata. Since nesting is not recommended, its context attribute envelope serves as a flat Atomic Parameter List. For more details, see the LinkedIn article “CloudEvents in the Dutch Energy Sector”.
Pagination Metadata: In many API implementations, pagination metadata is structured in one of two ways:
- As an Atomic Parameter List, where individual pagination attributes (e.g., currentPage, pageSize, offset, totalRecords, totalPages) are returned separately
- As a Parameter Tree, where a nested structure (e.g., Paging) encapsulates pagination details

Discussion Input

In RESTfull HTTP APIs, using multiple query parameters with a GET request can be considered an Atomic Parameter List. To keep this list compact and manageable — especially for error handling — we have decided to limit GET requests to a maximum of five query parameters. For more complex queries requiring additional parameters, a POST request with a query payload should be used instead.

While the QUERY method has been proposed as a safe, idempotent alternative to GET (allowing request bodies), it is not yet widely adopted. Until it gains broader support, POST with a request body remains the preferred approach for handling complex queries.

Parameter Tree

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 in the online pattern summary at 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 unnecessary 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.

Parameter Forest

Known Uses

Widely used, the Parameter Forest pattern consists of multiple Parameter Trees. A Parameter Tree has a single dedicated root node, while a Parameter Forest has multiple root nodes.

Examples:

GET /customers/abc123 – returns a tree (a single root with structured data)
GET /customers – returns a forest (multiple trees, each representing a customer)

Discussion Input

As noted in the book (p. 157), introducing an artificial root node can transform a forest into a tree. This raises the question: what is the added value of identifying the Parameter Tree as a distinct pattern?

Furthermore, one might argue that recursive Parameter Trees and Atomic Parameters are sufficient to describe complex data structures — meaning only two patterns instead of four, would be needed. However, explicitly identifying all four patterns as fundamental building blocks enhances design awareness, as these patterns are frequently used in practice, sometimes even unconsciously 😃.

Data Element

Known Uses

Not surprisingly, the Data Element pattern is widely used. This ubiquitous message-level pattern is primarily used in requests and responses and applied in the construction or API design phase.

Discussion Input

The pattern is closely tied to the principle of loose coupling. Domain model components used for API implementation should not be exposed directly. Instead, they should be encapsulated or mapped in a way that ensures separation between the internal workings of the system and the API’s external interface (for instance, in the form of a Data Transfer Object). By doing so, we achieve loose coupling between the client, the interface, and the implementation. This approach allows for greater flexibility and stability: while the API speaks a Published Language (PL), it remains decoupled from the internal domain model, which forms the Ubiquitous Language (UL) of a Bounded Context. This separation ensures that changes in the internal domain language do not impact the external interface.

Loose coupling also ties into the concept of data minimization. APIs should avoid returning large amounts of data in responses. Whenever possible, only the relevant fields or subsets of data needed by the user or application should be returned (“response shaping”). For larger datasets, Pagination should be implemented. The book proposes principles such as ‘less is more’ and ‘if in doubt, leave it out’ as useful guidelines for defining secure data contracts in APIs. This is in line with OWASP’s security best practices, which recommend minimizing the exposure of unnecessary or sensitive data in APIs to reduce security risks. Designing APIs with a minimalist mindset is crucial. Simplicity is key in the world of APIs.

It’s often easier to add new data elements or attributes than to remove them later. However, as more Data Elements are added, the need for patterns like the Wish List pattern increases. This pattern helps maintain a balance between data parsimony and flexibility. In this context, we have adopted the German word Datensparsamkeit (data parsimony) and would like to add, still in German: “In der Beschränkung zeigt sich der Meister.” (in English: “The master shows himself in restriction”). Both advocate for the elegance and efficiency of minimalism.

Aggressive Obsolescence

Known Uses

This pattern is not widely adopted in the energy sector in the Netherlands. However, a few usage examples exist in the Dutch government sector:

In the Kadaster BAG API Individual Queries (Basic Registration of Addresses and Buildings), the OpenAPI specification uses deprecated: true to indicate that the Accept-Crs header is deprecated, as well as the GET /adressen/zoek operation.
Allmanak: Directory Search for contact details of governments and politicians uses a well-defined deprecation policy.

Discussion Input

This pattern is primarily aimed at decommissioning entire APIs or outdated components, such as operations or message elements. The Sunset and Deprecation HTTP headers are specifically designed to indicate the planned decommissioning of a resource, method, or endpoint — but not for individual fields within a request or response body. These headers operate at the HTTP resource level, not at the payload or schema level.

When it comes to deprecating a field within a payload, several approaches are possible:

Announce it via changelogs and API documentation
Mark it as deprecated in the OpenAPI (OAS) specification
Remove it in the next API version (e.g., deprecated in v1, removed in v2)
Optionally use the HTTP Warning header (code 299) to surface a notice alongside the response if you want to highlight it at runtime

It’s worth noting that the use of the Deprecation header is currently a topic of discussion in the Dutch government sector, as the IETF has just published RFC 9745, which formally defines The Deprecation HTTP Response Header Field.

Experimental Preview

Known Uses

The book rightly points out that this pattern is similar to traditional beta testing (p. 378), which is why it’s commonly known as a beta API in our governmental and energy sector. Beta APIs provide early access to new features, allowing developers to experiment and give feedback before the API is finalized. They are publicly available but not yet stable – changes to their structure, behavior, or availability may still occur based on user input or internal priorities.

Some known uses are:

Rijkswaterstaat Beta Waterwebservices: A governmental API from the Netherlands for exchanging and combining water data. Feedback and updates are shared via the community developer portal
Beta APIs in the API registry of the DSO developers portal. Community interaction and feedback happen through GeoForum
Waarstaatjegemeente.nl beta API: An OData API from VNG that provides municipal-level data across various policy

Discussion Input

The use of experimental previews and beta programs is a valuable approach for collecting early feedback from users. It gives consumers the opportunity to influence development and helps teams prepare for future changes.

To support this process, a communication channel—such as a community portal or public forum—is essential. It facilitates feedback loops, announcements, and developer collaboration. In this context, a community portal is far from a luxury; it’s a key part of the ecosystem.

When using Semantic Versioning (SemVer), pre-release versions can be denoted by appending a hyphen followed by a series of dot-separated identifiers such as rc.n (with rc stading for release candidate). Examples: 1.0.2-rc.1, 2.0.0-beta.3 (Source: Logius API Guidelines – SemVer).

Limited Lifetime Guarantee

Known Uses

Dutch governmental organizations typically outline API lifecycles and deprecation policies in official documentation and service agreements. However, it’s uncommon for them to announce specific lifetime guarantees for their APIs. Instead, the standard practice is to give advance notice before making major changes or retiring an API version. This allows developers and stakeholders enough time to adjust their applications. While detailed lifetime guarantees are not always made public, the general recommendation — both within government bodies and the energy sector — is to provide at least 12 months notice before deprecating or significantly modifying APIs.

Link Element

Known Uses

The Linked Element pattern is used in a few Dutch government APIs but is less common in the Dutch energy sector. Known uses include the BAG and Kadaster APIs:

BAG (Basisregistratie Adressen en Gebouwen), the Basic Registration of Addresses and Buildings in the Netherlands.
Kadaster, the national land registry and mapping agency of the Netherlands. Kadaster won the Golden API Award in 2019.¹

These APIs provide up-to-date data on addresses, addressable objects, and buildings. The links in these APIs are formatted according to the HAL (Hypertext Application Language) specification.

Known uses in other domains are:

Discussion Input

Due to the availability of various hypermedia formats, the Dutch government and energy sector chose HAL for hypermedia implementation because its simplicity, compared to other formats, allows for quick and easy adoption. HAL is a universal and widely adopted specification for serializing hyperlinks in JSON responses. The Dutch government module on hypermedia provides the following guidelines:

Provide absolute URIs for hyperlinks (no relative links). “While relative links are more compact and may be practical when having multi-environment deployments, they introduce extra complexity for the client and may potentially result in erroneous behaviour (e.g. when dealing with trailing slashes or dot segments).” (source: https://docs.geostandaarden.nl/api/API-Strategie-mod-hypermedia/#hypermedia).
The usage of hypermedia is not intended to implement HATEOAS. “An API specification must offer a strict and stable contract between server and client, which should guarantee backwards compatibility during the full lifetime of a given major version, whereas true HATEOAS advocates continually evolving interfaces requiring little to no prior knowledge about how to interact with the application.” (source: https://docs.geostandaarden.nl/api/API-Strategie-mod-hypermedia/#hypermedia).
Navigation controls are only allowed to point to other APIs when they share governance and security context.

Nowadays, only a small fraction of modern web APIs fully embrace hypermedia principles, and this is certainly true for the Dutch government and energy sector. In our energy sector Linked elements are primarily used for implementing pagination and will also be used for lightweight (‘thin’) event notifications.

The book suggests incorporating semantics into the Link Element pattern. Semantic links go beyond simple navigation by conveying meaning about the relationship between resources. These links not only provide a destination URL but also help the consumer understand the context of the link and what the next step or related resource might be. In APIs, semantic links describe relationships between resources using well-defined semantics. For example, in HAL, JSON-LD, or Atom feeds, a link with "rel": "next" indicates the next page in pagination. This helps users and systems understand the link’s purpose and how it fits within the larger context of the application.

Pricing Plan

Known Uses

Most government APIs are freely available under an open license (CC0). However, they often come with a fair use policy or limits on the number of requests. Similarly, open data APIs from grid operators are generally free, but accessing specific or real-time data may involve additional costs.

A number of government APIs with a pricing plan:

The Chamber of Commerce offers various APIs (Trade Register Search, Basic Profile, Establishment Profile, Naming) for which you need to sign an agreement and pay a subscription fee. The exact rates can be found in the KVK rate overview on their developer portal.
Standard access to Mijn Kadaster is free, but subscription fees apply for specialized services like Kadaster-on-line, KIK Inzage, and the Archiefviewer. Custom APIs are priced separately.

Discussion Input

The Dutch API strategy mentions that, in some cases, the use of APIs may incur charges. This is particularly relevant for governments, as it enables them to pass on costs to individual organizations and their partners in the value chain. API users may be required to pay for usage, with pricing models including Freemium, Tiered, Pay-as-you-go, and cost allocation based on a fixed price per time unit. These approaches closely match the subscription-based and usage-based pricing models discussed in the book. The third model from the book, market-based pricing, is less commonly applied in the public sector.

Request Bundle

Known Uses

Dutch government APIs on developer.overheid.nl demonstrate varying levels of support for bulk requests, primarily through their implementation of the OData protocol. APIs from organizations such as CBS and the “Tweede Kamer” utilize OData v4, which inherently supports batch operations for both queries and data modifications.

This pattern is rarely used within the energy sector: bulk data retrieval is handled outside the RESTful HTTP APIs via extract services or data-dump interfaces.

Some other known uses within Dutch government are:

Autorisaties API: Using curl -X GET https://autorisaties-api.vng.cloud/api/v1/applicaties?clientIds=123,456,789, the ‘applications’ collection can be queried using multiple clientIds as query parameters.
Using an older version of the BRP API, it was possible to query registered individuals using multiple citizen service numbers: curl -X GET https://www.haalcentraal.nl/haalcentraal/api/brp/ingeschrevenpersonen?burgerservicenummer=999993653,999991723,999995078

Discussion Input

Requesting multiple resources in a single API call raises several considerations:

Response size limits
Handling partial failures (e.g., what happens if one ID is invalid?)
RESTful HTTP API design: should multiple values be passed as query parameters or as path parameters?

When designing APIs that need to retrieve multiple resources by their IDs, there are different approaches. Dutch government APIs use a single query parameter with comma-separated values: GET /customers?ids=a1,b2,c3. This approach is concise and widely used for filtering and OTTO’s API guidelines explicitly recommend this format for filtering by multiple values: https://api.otto.de/portal/guidelines/r000062.

In the future, the QUERY HTTP method will likely be used for these bulk-request retrieval scenarios.

Semantic Versioning

Known Uses

Dutch governmental and energy sector APIs commonly follow a versioning pattern using three numbers in the format x.y.z, where each part indicates a different level of change. The terminology for semantic versioning is consistent with the widely accepted standard, as described in the Semantic Versioning pattern and the Semactic Versionning specification:

x -– Major: Breaking changes
y –- Minor: Backward-compatible extensions
z –- Patch: Backward-compatible fixes

This pattern does not prescribe how the version identifiers should be structured or applied. In RESTful HTTP APIs, semantic versioning is typically expressed in the info.version field of the OpenAPI Specification (OAS). According to the DSO API Strategy, it is recommended to include an api-version header in the HTTP response to explicitly state the semantic version of the API. Occasionally, a Warning header is also used to indicate deprecation.

Example: api-version in HTTP Response in the ‘Retrieve spatial plans’ Omgevingswet API.

Known uses of api-version and Warning headers are:

BAG API (Basisregistratie Adressen en Gebouwen – Basic Registration of Addresses and Buildings)
Kadaster API (Dutch Land Registry and Mapping Agency)

In the energy sector, the CloudEvents specification includes a dataversion extension attribute, which represents the semantic version of the event data carried in the payload.

Discussion Input

It is important to distinguish between the API interface and its implementation. The book rightly points out that the version numbers of an interface and its implementation(s) will usually not match (p373). A common misconception is interpreting the info.version field in an OpenAPI Specification (OAS) as the version of the API itself. In reality, the info.version field refers to the version of the OpenAPI description, not the API it describes. In other words, it reflects the version of the documentation, not the underlying API implementation.

A version change – whether minor or major – should often be accompanied by release notes (or a changelog within the API specification itself) to detail the changes. This is especially important for major version upgrades, which may bundle multiple changes that impact consumers.

Pattern Adoption Stories from Readers: Dutch Government & Energy Sector (4/5)

Known Uses

Discussion Input

Known Uses

Discussion Input

Known Uses

Discussion Input

Recommended Reading

Known Uses

Discussion Input

Known Uses

Discussion Input

Recommended Reading

Known Uses

Discussion Input

Recommended Reading

Known Uses

Discussion Input

Known Uses

Known Uses

Discussion Input

Known Uses

Discussion Input

Known Uses

Discussion Input

Recommended Reading

Known Uses

Discussion Input

Recommended Reading