Published: 27 January 2024
Known Uses
The Two in Production pattern is actively employed in the API lifecycle management strategy of the Dutch government. It is interesting to mention that in the DSO API strategy, initially, the support was limited to a maximum of three versions of an API (“three in production”), comprising two major versions and one minor one. Both old and new versions (up to a maximum of three) of an API were concurrently offered for a limited transition period (up to one year), with two major versions available. Through the optional request header, one minor/patch version could be specified. This means that, for instance, in a (pre)production or integration environment, alongside, for example, v1 and v2, there was still the option to access one “older” or, alternatively, one “newer” minor/patch version of these APIs. This version could then be accessed through the request header. This approach was later discontinued due to significant operational complexity: running multiple minor/patch versions in parallel proved unnecessarily complicated. Furthermore, the use of an api-version request header conflicted with employing the version number in the URI. However, it was decided to include the api-version (full version number) in the response headers for every API call, since the URI only contains the major version. This information could then be used for logging, debugging or auditing purposes. In cases where an intermediate networking component returns an error response (e.g., a reverse proxy enforcing access policies), the version number may be omitted.
- https://gitdocumentatie.logius.nl/publicatie/api/adr/#/core/transition-period: When releasing a new major API version, the old version must remain available for a limited and fixed deprecation period. Offering a deprecation period allows clients to carefully plan and execute the migration from the old to the new API version, as long as they do this prior to the end of the deprecation period. A maximum of two major API versions may be published concurrently.
- https://developer.overheid.nl/apis/kadaster-bag-current/specificatie/production: Sunsetting example and usage of RFC7234. With a Warning response header [RFC7234] included in all responses from the old APIs, users are actively alerted about the upcoming phase-out.
In the Dutch energy sector, we have opted for a maximum of three versions in production, allowing clients more time to upgrade and adapt within the managed evolution timeframe. This choice aims to strike a good balance between provider complexity and the pace of client adaptation.
Known Uses
An important question is how many API versions in production should be offered in parallel. As stated very well in the book (page 391): the variant N in production gives clients more time and options to upgrade, but puts more maintenance effort and operational cost on the provider side. As always, it depends, and it is a trade-off between provider maintenance activities and pace of adapting to new major versions by clients. In any case, there should be a clear policy that defines the maximum number of major versions to be offered. The overall objective would be to keep the number of parallel major versions limited.
Read the complete pattern on api-patterns.org