Pattern: Eternal Lifetime Guarantee

How can a provider support clients that are unable or unwilling to migrate to newer API versions at all?


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

Pattern: Eternal Lifetime Guarantee

a.k.a. Here to Stay, Unlimited Support Period

Context

An API has been made available to at least one client. The integration with its clients has been successful, and these client are used in production. However, one or more of the clients cannot be asked to upgrade to use the latest API version – or cannot be developed further at all.

Problem

How can a provider support clients that are unwilling or unable (e.g., due to not being able to invest the required effort) to migrate to newer API versions at all?

Forces

Eternal Lifetime Guarantee must resolve the following forces:

  • No changes in the client required due to API changes.
  • Making it possible for the provider to improve the API and change it to accommodate to new requirements of different clients.
  • Minimizing the maintenance effort to support old clients.
  • Ability to upgrade API infrastructure technologies.
  • Ability to fix security issues.
  • Respecting/acknowledging power dynamics between API provider and client, for instance, the ability of clients to steer API design and evolution.

Pattern forces are explained in depth in the book.

Solution

As an API provider, guarantee to never break or discontinue access to a published API version.

Example

A national bank wants to offer a service that retrieves a list of ISO currency codes that are used in a country at a given date. Because this API is quite simple and the national bank expects many users to invoke this API, it offers this API with an Eternal Lifetime Guarantee so that clients can rely on this service to be available for as long as the national bank can be expected to be open for business (note that only the API contract is fully stable in this example; the returned data and the API implementation might change over time).

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

Eternal Lifetime Guarantees is used by a few organizations (including software vendors and alliances) that have different customer types who value sustainability due to the high impact of breaking changes on their own applications and tools:

  • SAP used to offer an Eternal Lifetime Guarantee (or came close to that) to its paying customers integrating via official and certified Remote Function Calls (RFCs).
  • The local Java APIs for IDE extensions in Eclipse adhere to the API Prime Directive that when “evolving the Component API from release to release, do not break existing clients”. Note that this directive only applies to public APIs. In practice, many API clients also use internal APIs that are prone to incompatibility problems.
  • HTTP 1.1 and XML 1.0 are two examples of W3C standards that have remained stable and supported for more than a decade now.

More Information

Related Patterns

The guarantee is communicated in the API Description and/or in a Service Level Agreement.

Compared to other patterns in this evolution category, Eternal Lifetime Guarantee is an extreme guarantee that is theoretically unlimited. All other life cycle patterns (Limited Lifetime Guarantee, Two in Production, Aggressive Obsolescence, and Experimental Preview) try to limit the guarantee so that there are boundaries for how long backwards-compatibility is to be fulfilled.

An Eternal Lifetime Guarantee may have an explicit Version Identifier, but this is not necessary.

Other Sources

“Managed Evolution” shares information on service governance and versioning. The SLA example in Side-Story 3.5 shows an SLA that states “no phase-out planned” Murer, Bonati, and Furrer (2010).

References

Murer, Stephan, Bruno Bonati, and Frank Furrer. 2010. Managed Evolution - a Strategy for Very Large Information Systems. Springer.