Pattern Sections
Pattern: Two in Production
a.k.a. Parallel Versions, Rolling Update Policy
Context
An API evolves and new versions with improved functionality are offered regularly. At some point in time, the changes of a new version are not backwards compatible anymore, thereby “breaking” existing clients. However, clients, especially of a Public API or a Community API, evolve at different speeds; some of them cannot be forced to upgrade to the latest version in a short time frame because the release cycles of the provider(s) and client(s) do not align well with each other.
Problem
How can a provider gradually update an API without breaking existing clients but also without having to maintain a large number of API versions in production?
Forces
Two in Production balances the following forces:
- Allow the provider and the client to follow different life cycles so that a provider can roll out a new API version without breaking clients using the previous API version.
- Guarantee that API changes do not lead to undetected backwards-compatibility problems between clients and the provider.
- Ensure the ability to roll back if a new API version is designed badly.
- Minimize changes to the client caused by API changes.
- Minimize the maintenance effort for supporting clients relying on old API versions.
Pattern forces are explained in depth in the book.
Solution
Deploy and support two versions of an API endpoint and its operations that provide variations of the same functionality but do not have to be compatible with each other. Update and decommission the versions in a rolling, overlapping fashion.
As a variant, consider to support more than two versions, for instance three.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
A business software vendor releases an API (Version 1) for its Enterprise Resource Planning (ERP) system. In the continued development of the ERP system, the payroll part of the API provided by its HR module is extended; at some point, new pension plan management features break this API part. Because the vendor uses the Two in Production pattern, it releases its updated ERP both with the old API (Version 1) and with the new API (Version 2). Existing customers can continue to use Version 1 when they start using the ERP update and migrate to Version 2 gracefully later. New customers who need the new, incompatible pension plan management features can start to use the new API Version 2 right away.
With the next release, the software vendor again releases a new API (Version 3) and removes support for Version 1; Versions 2 and 3 are now supported. Customers that still use Version 1 are cut off until they have migrated to one of the two more recent versions (that they can be redirected to). Clients using Version 2 can stay on it until API Version 4 is released and Version 2 removed, and so on.
Are you missing implementation hints? Our papers publications provide them (for selected patterns).
Consequences
The resolution of pattern forces and other consequences are discussed in our book.
Known Uses
Known uses for this pattern include:
- Terravis Lübke and Lessen (2016) offers two major versions in parallel for two years.
- A large bank in Europe keeps two major versions (see Semantic Versioning for definition of “major”) in parallel.
- The Dynamic Interface described in Brandner et al. (2004) applies the pattern as well.
- GitHub offers a v3 API, but also the next version in parallel.
- Facebook describes a rolling release and update policy as well, which is a defining characteristic of Two in Production. See their documentation page “Platform Versioning”.
More Information
Related Patterns
The usage of this pattern usually requires the Version Identifier pattern in order to distinguish the API versions that are currently active and supported concurrently. Fully compatible versions, e.g., as indicated by the patch version in Semantic Versioning can replace active versions without violating the Two in Production constraints. This should be reported in the API Description and/or the Service Level Agreement.
Aggressive Obsolescence can be used to force clients to stop using the older API version and migrate to the newer one so that the provider can introduce an even newer API version. If the client requires more guarantees on the expiration date of the old API version, the Limited Lifetime Guarantee pattern might be more applicable. An Experimental Preview can be one of the versions in production, although the provider should indicate whether the Experimental Preview counts towards the Two in Production.
Other Sources
“Managed Evolution” covers life cycle management on a general level, but also dives into API versioning. Section 3.5.4 reports a combined usage of Semantic Versioning and Two in Production. Three versions are reported to have proven as a good compromise between provider complexity and adaptation pace Murer, Bonati, and Furrer (2010).
“Challenges and benefits of the microservice architectural style”, a two-part article on the IBM Developer portal Fachat (2019), recommends this pattern.