Pattern Sections
Pattern: Limited
Lifetime Guarantee 
a.k.a. Fixed Lifetime Guarantee, Guaranteed Availability Period
Context
An API has been published and made available to at least one client. The API provider cannot manage or influence the evolution roadmaps of its clients, or the damage (e.g., financial or reputation) caused by forcing clients to change their implementation is considered high. Therefore, the provider does not want to make any breaking changes in the published API, but still wants to improve the API in the future.
Problem
How can a provider let clients know for how long they can rely on the published version of an API?
Forces
Limited Lifetime Guarantee must balance the following forces:
- Make client-side changes caused by API changes plannable.
- Limit the maintenance effort for supporting old clients.
Pattern forces are explained in depth in the book.
Solution
As an API provider, guarantee to not break the published API for a fixed timeframe. Label each API version with an expiration date.
Example
One example for a Limited Lifetime Guarantee was the introduction of the International Banking Account Numbers (IBAN) in Europe. The limited lifetime was specified in a 2012 resolution of the European parliament granting a period until 2014 after which the old, national account numbers needed to be replaced by the new standard; the use of IBANs became compulsory after that. This regulatory requirement of course had impact on software systems that have to identify accounts. The services offered by such systems had to issue a Limited Lifetime Guarantee for the old operations, which used the old account numbers. This example shows that versioning and evolution strategies are not only decided by the API provider alone, but can also be influenced or even mandated by external forces (such as legislation or industry consortia).
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
The Limited Lifetime Guarantee pattern is used by several organizations that have different customer types:
- Facebook offers a two-year guarantee on its core API and SDK for everyone, including anonymous clients. See the documentation page Platform Versioning.
- Google Adwords offers a 10-month guarantee.
- eBay works with deprecation policies.
- Twitter discontinued support for HTTP Basic Authentication on 31.8.2010. The change was announced on 28.4.2010 together with a dedicated countdown clock website and the initial deadline was set for June 30. All client apps developers had to switch to OAuth by that time.
- Terravis Lübke and Lessen (2016) offers two major versions in parallel for two years.
More Information
Related Patterns
The Limited Lifetime pattern mixes properties of the Eternal Lifetime Guarantee and Aggressive Obsolescence patterns: the API must not change in an incompatible way within the announced time span. However, the time span serves as an integrated, implicit deprecation mechanism. After it has elapsed, the provider may make any changes including breaking ones or discontinue the expired API version altogether.
The API Description and, if present, a Service Level Agreement should indicate the actual expiration date for the API version in order to inform API clients by when they need to take action and upgrade. More lenient approaches, giving the provider more freedom with respect to releasing incompatible updates, are presented in the Aggressive Obsolescence and Two in Production patterns. Limited Lifetime and these two patterns can be used together.
A Limited Lifetime Guarantee usually has an explicit Version Identifier.
Other Sources
Managed Evolution Murer, Bonati, and Furrer (2010) gives rich advice on service versioning and service management processes, for instance including quality gates. Section 3.6 mentions service retirement.