also known as: Decrease Lifetime Guarantee, Soften Lifetime Commitment
Context and Motivation
An API runs in production. Its compatibility and extensibility characteristics are expressed in the form of one or more Evolution Patterns, including Experimental Preview, Aggressive Obsolescence, Limited Lifetime Guarantee, and Two in Production. These patterns differ in the way/frequency the provider is able to introduce breaking changes.1
As an API provider, I want to take back some of the rather strict lifetime, stability, and support guarantees given for an API endpoint and its elements so that I can update the API more freely and more often (including breaking changes).
Stakeholder Concerns (including Quality Attributes and Design Forces)
- Reducing the number of versions that run in production and reducing their lifetime guarantees reduces the maintenance effort. See Tighten Evolution Strategy for more explanations.
- Less code to be maintained over time means less maintenance costs. Sometimes, a planned (or managed) obsolescence approach is followed. Tighten Evolution Strategy also discusses this concern.
- Not having to maintain different versions in parallel makes the provider team more flexible, but limits the options client developers have. Again, Tighten Evolution Strategy features this quality as well.
“Interface Evolution Patterns — Balancing Compatibility and Extensibility across Service Life Cycles” [Lübke et al. 2019] elaborates on the desired qualities that evolution patterns are generally confronted with (PDF).
Initial Position Sketch
The following provider specification does not yet define any life cycle guarantee (notation: MDSL):
API provider SampleAPIProvider1 offers SomeDemoContract at endpoint location "http://www.testdomain.io:80/path/subpath" via protocol HTTP binding resource SampleAPIProvider1Resource
- API endpoint and its API description (business and technical contract).
- Service Level Agreement (SLA) that accompanies or is part of API Description.
Smells / Drivers
- Feature/release inertia a.k.a. stale roadmap
- Providers are reluctant to introduce new features because of the commitments made and guarantees given to existing API users (for example, in an SLA).
- Resistance to change caused by uncertainty
- A provider has made many assurances/guarantees to clients and is now reluctant to apply other API refactorings because it is afraid of disrupting these clients.
Relaxing guarantees might be more subtle than tightening them. Therefore, fewer transitions make sense:
- Reduce the number of supported versions from N In Production to N-1 in Production.
- No longer support Two in Production but still give a Limited Lifetime Guarantee for a single API version.
- Replace a Limited Lifetime Guarantee with an Aggressive Obsolescence policy.
- Revert from an (unrealistic, theoretical) Eternal Lifetime Guarantee to a (fixed, predefined) Limited Lifetime Guarantee.
Note that we do not recommend to go down to an Experimental Preview.
Target Solution Sketch (Evolution Outline)
The life cycle guarantee primarily is a documentation item (first and foremost):
When relaxing the lifetime guarantees, an MDSL contract may change from:
API provider SampleAPIProvider1 version 1.0.0 offers SomeDemoContract at endpoint location "http://www.testdomain.io:80/path/subpath" via protocol HTTP binding resource SampleAPIProvider1Resource provider governance LIMITED_LIFETIME_GUARANTEE
API provider SampleAPIProvider1 version 1.1.0 offers SomeDemoContract at endpoint location "http://www.testdomain.io:80/path/subpath" via protocol HTTP binding resource SampleAPIProvider1Resource provider governance AGGRESSIVE_OBSOLESCENCE
The Evolution Patterns on the MAP website list real-world known uses of the patterns (and related changes over time).
Hints and Pitfalls to Avoid
Apply this refactoring when existing clients complain, for instance about the slow speed of API innovations.
When applying the refactoring, make sure to:
- Perform a cost-benefit analysis, preferably a quantitative rather than a qualitative one.
- Minimize incompatible changes and apply semantic versioning when releasing.
- Communicate changes early, clearly, and continuously so that clients are not surprised (TELL).
Introduce Version Mediator can be applied if lifetime guarantees are weakened and some clients are unable to migrate to a newer, incompatible version. Introduce Version Identifier might have to be applied first so that clients can learn about versions and their compatibility characteristics.
This refactoring is the opposite of Tighten Evolution Strategy. Both these actions actually do not change the API structure, but its developmental qualities and support properties.
Microservice Domain-Specific Language (MDSL) specifications have an optional SLA section and a
provider governance section in their API provider parts, which is explained in the language documentation.
Lübke, Daniel, Olaf Zimmermann, Cesare Pautasso, Uwe Zdun, and Mirko Stocker. 2019. “Interface Evolution Patterns: Balancing Compatibility and Extensibility Across Service Life Cycles.” In Proceedings of the 24th European Conference on Pattern Languages of Programs. EuroPLop ’19. New York, NY, USA: Association for Computing Machinery. https://doi.org/10.1145/3361149.3361164.