Published: 28 April 2025
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 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 REST 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:
- 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’s 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.
Recommended Reading
- Erik Wilde on Semantic Versioning: Hyrumizing your API: avoid observable behavior that consumers may depend on
- Dutch Government REST API Design Rules 2.0.2
- LinkedIn discussion topic: what does the info.version property in an OpenAPI document actually represent?
Read the complete pattern on api-patterns.org