API Design Pattern of the Week 18: Two in Production
A pattern from the book “Patterns of API Design: Simplifying Integration with Loosely Coupled Message Exchanges”
The first 14 patterns in the “API Design Pattern of the Week” series came as LinkedIn articles; Pattern 15 was Rate Limit, Pattern 16 Context Representation, Pattern 17: Version Identifier; Pattern 19: Public API.
Note: This online excerpt of the pattern predates its final version in the book.
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.
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 solves this problem, balancing 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.
Solution Sketch
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.
A visualization of 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.
Consequences
Pattern forces resolution and other consequences are discussed in our book.
Known Uses
See pattern coverage on our website.
Related Patterns
The usage of this pattern usually requires a Version Identifier 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 an older API version and migrate to a 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, recommends this pattern (Fachat 2019).
References
Fachat, André. 2019. “Challenges and Benefits of the Microservice Architectural Style.” IBM Developer.
Murer, Stephan, Bruno Bonati, and Frank Furrer. 2010. Managed Evolution — a Strategy for Very Large Information Systems. Springer.
Zimmermann, Olaf and Stocker, Mirko and Lübke, Daniel and Zdun, Uwe and Pautasso, Cesare. 2022. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges, Vaughn Vernon Signature Series, Addison-Wesley Professional.
All series elements are listed in this story. This pattern originally appeared on our website https://api-patterns.org. We follow the standard format for patterns, from context to forces, problem, solution, consequences and known uses. Find out why.
Copyright © 2019–2023 by the authors. All rights reserved.
See terms and conditions of use.
