Relax Evolution Strategy

Updated:

 Note: This is a preview release and subject to change. Feedback welcome! Contact Information and Background (PDF)

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)

#maintainability
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.
#cost
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.
#flexibility
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

Relax Evolution Strategy: Initial Position Sketch

Relax Evolution Strategy: Initial Position Sketch

Targets:

Design Smells

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.

Instructions (Steps)

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):

Relax Evolution Strategy: Target Solution Sketch

Relax Evolution Strategy: Target Solution Sketch

Example(s)

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

to:

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.

Related Content

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.

References

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.

  1. Alternatively (but only justified in rare cases), the provider might decide not to do so at all and guarantee an Eternal Lifetime Guarantee. ↩