Relax Evolution Strategy

Context and Motivation

An API runs in production. Its Service Level Agreement states its compatibility and extensibility characteristics, for instance in the form of one or more of the Evolution Patterns Experimental Preview, Aggressive Obsolescence, Limited Lifetime Guarantee, and/or Two in Production [Zimmermann et al. 2022]. These patterns describe service lifecycle management strategies that differ in the way and the frequency the provider is able to introduce breaking changes.¹

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 earlier so that I can update the API more freely and more often (including breaking changes).

Stakeholder Concerns

#cost

Less code to be maintained over time means less maintenance costs. Sometimes, a planned (or managed) obsolescence approach is followed.

#flexibility

Not having to maintain different versions in parallel makes the provider team more flexible, but limits the options client developers have.

#maintainability

Reducing the number of versions that run in production and reducing their lifetime guarantees reduces the maintenance effort.

Initial Position Sketch

Figure 1: Relax Evolution Strategy: Initial Position Sketch. The API Provider offers an API endpoint as Two in Production with a Limited Lifetime Guarantee.

This refactoring targets an API endpoint and its API Description (business and technical contract), as well as the Service Level Agreement (SLA) that accompanies its API Description. See Figure 1 for the initial position sketch.

Smells

API rot and semantic diffusion

The API does not get to the POINT. It has accumulated technical debt due to the introduction of new features in a compatible but unclean way in order to not make breaking changes. Its roles and responsibilities suffer from semantic diffusion.

API version sprawl

Many API versions for different clients are active in parallel because otherwise no changes could be made.

Customer complaining about lack of API release roadmap agility

One or more customers are unhappy with the pace of API development, which is slowing down the development of their entire system. They are actively asking for fewer guarantees in exchange for faster introduction of the features they need.

Feature/release inertia a.k.a. stale roadmap

API providers are reluctant to introduce new features because of the commitments made and guarantees given to existing API users (for example, in an SLA). Update requests from the clients/communities are present, but API provider is slow to respond to them. This is particularly hurtful in customer-supplier relationships.

Resistance to change caused by uncertainty

A provider has made many assurances/guarantees to clients and is now reluctant to apply other interface refactorings because it is afraid of disrupting these clients.

Apply this refactoring when existing clients complain, for instance about the slow speed of API innovations.

Instructions

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.

Figure 2 presents a state diagram of common transitions. Note that we do not claim to have captured all possible ones, but those to be observed in practice.

Figure 2: Transitions to relaxing lifetime guarantees of an API.

Note that we do not recommend going down to Experimental Preview. Customers already using the API in production are unlikely to welcome such downgrade.

Target Solution Sketch (Evolution Outline)

The life cycle guarantee primarily is a documentation item (first and foremost). See Figure 3 for a visualization.

Figure 3: Relax Evolution Strategy: Target Solution Sketch. The API Provider has reduced the guarantees given to Limited Lifetime Guarantee and dropped the Two in Production.

If strong commitments or guarantees have already been made to existing clients, reducing these guarantees for the current version may not be feasible without risking contractual or trust issues. Therefore, this refactoring is best applied when planning and releasing a new major version, allowing the provider to set new, less strict guarantees from the beginning.

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/path/subpath"
    via protocol HTTP 
  binding 
    resource SampleAPIProvider1Resource
  provider governance TWO_IN_PRODUCTION

to:

API provider SampleAPIProvider1 version 1.1.0
  offers SomeDemoContract 
    at endpoint location "http://www.testdomain.io/path/subpath"
    via protocol HTTP 
  binding 
    resource SampleAPIProvider1Resource
  provider governance LIMITED_LIFETIME_GUARANTEE

The online versions of the Evolution Patterns list real-world known uses of the patterns (and related changes over time).

Hints and Pitfalls to Avoid

When applying the refactoring, make sure to:

• Perform a cost-benefit analysis, preferably a quantitative rather than a qualitative one.
• Consult with the API owners on the business level and possibly additional stakeholders such as legal offices to check whether the impact of the refactoring on the Service Level Agreement and other contractually relevant API documentation is acceptable. Involve these stakeholders early.
• Minimize incompatible changes and apply Semantic Versioning when releasing.
• Communicate changes early, clearly, and continuously using Test, Explain, Let Know, and Learn (TELL) [Stocker and Zimmermann 2023] on/for the architectural level so that clients are not surprised.

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 do not change the API structure, but its developmental qualities and support properties.

“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.

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.

Stocker, Mirko, and Olaf Zimmermann. 2023. “API Refactorings to Patterns: Catalog, Template and Tools for Remote Interface Evolution.” In Proceedings of the 28th European Conference on Pattern Languages of Programs. EuroPLop ’23. New York, NY, USA: Association for Computing Machinery. https://doi.org/10.1145/3628034.3628073.

Zimmermann, Olaf, Mirko Stocker, Daniel Lübke, Uwe Zdun, and Cesare Pautasso. 2022. Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges. Addison-Wesley Signature Series (Vernon). Addison-Wesley Professional.

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