Pattern: Two in Production

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?


The final version of this pattern is featured in our book Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges.

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:

Figure 1: Version Life Cycles when Using Two In Production

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:

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.

References

Brandner, Michael, Michael Craes, Frank Oellermann, and Olaf Zimmermann. 2004. “Web Services-Oriented Architecture in Production in the Finance Industry.” Informatik-Spektrum 27 (2): 136–45. https://doi.org/10.1007/s00287-004-0380-2.
Fachat, André. 2019. “Challenges and Benefits of the Microservice Architectural Style.” IBM Developer. https://developer.ibm.com/articles/challenges-and-benefits-of-the-microservice-architectural-style-part-2/.
Hohpe, Gregor, and Bobby Woolf. 2003. Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions. Addison-Wesley.
Lübke, Daniel, and Tammo van Lessen. 2016. “Modeling Test Cases in BPMN for Behavior-Driven Development.” IEEE Software 33 (5): 15–21. https://doi.org/10.1109/MS.2016.117.
Murer, Stephan, Bruno Bonati, and Frank Furrer. 2010. Managed Evolution - a Strategy for Very Large Information Systems. Springer.
Pautasso, Cesare, Olaf Zimmermann, Mike Amundsen, James Lewis, and Nicolai M. Josuttis. 2017. “Microservices in Practice, Part 1: Reality Check and Service Design.” IEEE Software 34 (1): 91–98. https://doi.org/10.1109/MS.2017.24.
Richardson, Chris. 2016. “Microservice Architecture.” http://microservices.io.