Atomic Parameter

_{Published: 22 April 2025}

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 Dutch government sector:

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 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 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

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) has 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.

Best Practices for Using Enums in API Contracts: 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.