Pattern Sections
Pattern: Aggressive
Obsolescence 
a.k.a. Early Sunset, Planned Obsolescence (a term discussed in Pautasso et al. (2017a))
Context
Once an API has been released, it evolves and new versions with added, removed or changed functionality are offered. In order to reduce effort, API providers do not want to support certain functionalities for clients anymore, e.g., because they are no longer used regularly or are superseded by alternative versions.
Problem
How can API providers reduce the effort for maintaining an entire API or its parts (such as endpoints, operations, or message representations) with guaranteed service quality levels?
Forces
Aggressive Obsolescence needs to balance the following forces:
- Minimizing the maintenance effort (e.g., limiting support for old clients)
- Reducing forced changes to clients in a given time span as a consequence of API changes
- Acknowledging and respecting power dynamics between API provider and client, for instance, the ability of clients to steer API design and evolution.
- Respecting commercial goals and constraints, e.g., impact on Pricing Plan
Pattern forces are explained in depth in the book.
Solution
Announce a decommissioning date to be set as early as possible for the entire API or its obsolete parts. Declare the obsolete API parts to be still available but no longer recommended to be used so that clients have just enough time to upgrade to a newer or alternative version before the API parts they depend on disappear. Remove the deprecated API parts and the support for it as soon as the deadline has passed.
Sketch
A solution sketch for this pattern from pre-book times is:
Example
A payment provider offers an API that allows clients to instruct payments from their accounts to other accounts. Accounts can be identified by old-fashioned, country-specific account and bank numbers or by International Bank Account Number (IBAN).1 Because IBANs are the new standard and the old account and bank numbers are rarely used, the API provider decides to not support the old numbers anymore. This allows the provider to delete parts of its implementation, thereby reducing the maintenance effort.
In order to allow old clients to migrate to the IBAN scheme, the provider publishes a removal announcement on its API documentation Web page, marks the account and bank number as deprecated in the API documentation, and notifies clients that are registered with the service. The announcement states that the old, country-specific functionality will be removed after one year.
After one year, the payment provider deploys a new implementation of the API that has no support of the old account and bank numbers and removes the old, country-specific attributes from its API documentation. Calls to the old API version fail from now on.
It is notable that in this case, legislature had also specified a transition period to the IBAN system along the lines of deprecating the old, country-specific account number scheme.
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 Aggressive Obsolescence Pattern is frequently used in large APIs. Some examples are:
- Google has sometimes been reported to implement this pattern in the context of its online services, e.g., Google Wave.
- Riot Games uses (or used) this pattern for the Riot Games API.
- Microsoft uses a 24 month deprecation period on Microsoft Graph.
- Aggressive Obsolescence is also used in local programming APIs, e.g., the ZEND Framework.
- Mike Amundsen reports the use of this pattern in “Microservices in Practice, Part 2” Pautasso et al. (2017b).
More Information
Related Patterns
Other patterns defining the life cycle also deal with the discontinuation of services. Several strategies can be employed, as outlined in the Two in Production, Limited Lifetime Guarantee and Eternal Lifetime Guarantee patterns. In contrast, our Aggressive Obsolescence pattern can be used in a more fine-grained way because it aims at removing functionality from an API, which is not necessarily bound to syntactic units: While other versioning schemes are attached to operations or set of operations, only certain representation elements might get deprecated and removed in Aggressive Obsolescence, thereby allowing less obstructive changes.
Another difference to other patterns is that Aggressive Obsolescence always uses relative timeframes for removing functionality: Because functionality becomes obsolete during the lifetime of an API, it gets flagged deprecated within its active period and the deprecation period runs from this time onwards. In contrast, Two in Production or Limited Lifetime Guarantee can be used with absolute timeframes based on the initial release date.
Finally, the pattern cannot only be applied proactively, but also reactively during API maintenance.
The pattern may or may not use a Version Identifier. If present, an API Description or a Service Level Agreement should indicate the usage of this pattern with the corresponding deprecation metadata.
Other Sources
“Managed Evolution” Murer, Bonati, and Furrer (2010) shares general information on service governance and versioning, for instance how to define quality gates and how to monitor traffic. Chapter 7 deals with “Measuring the Managed Evolution”. An empirical study on deprecation in the context of RESTful APIs can be found in Yasmin, Tian, and Yang (2020).
References
IBANs originally were developed in Europe, but are now used in other parts of the world as well. They have become an ISO standard.↩︎