API Lifecycle Management: Deprecation and Sunsetting

APIs are products and go through the same lifecycle as all products. They get created, see some usage, get improved over time based on feedback and product management, but eventually, they will be discontinued.

This may either be the case because an improved (but different) product is available, or it simply may not make sense anymore to distribute the product.

Important aspect

An important aspect of Developer Experience (DX) of an API product is to make sure that for developers they are easy to use and that relying on them is a safe thing to do.

One aspect of DX is that it’s useful for a product to be able to make statements about its own lifespan.

You can look at this as the equivalent of the expiration dates you find on food products in supermarkets. Because of these dates (and other useful labels such as nutrition and allergen information), it’s safer and more convenient to use food than without that information being available.

API Lifecycle Management: Deprecation and Sunsetting

Looking at APIs and their end-of-life, there are two useful pieces of information that can be exposed in an API:

• Deprecation means that the API is no longer recommended for use, even though it is still operational. This may be because it will be discontinued, or because a new version of the product is available, and consumers are encouraged to switch to that newer version.
• Sunsetting means that the API will be shut down, meaning that at the announced time, the API will no longer be available. This is a hard stop for consumers who should be able to plan ahead regarding how they are going to handle this.

It makes a lot of sense to make these things part of the API design from the very beginning so that consumers can more safely use the product.

The mechanisms presented here are easy to use. They both depend on using HTTP header fields which can be used to announce the deprecation or sunsetting of an API:

• “The Deprecation HTTP Header Field” currently is an Internet Draft (I-D) and defines the Deprecation HTTP header field.
• “The Sunset HTTP Header Field” is Internet RFC 8594 and defines the Sunset HTTP header field.

Implementation

Implementing these HTTP header fields in an API can be done in various ways, either by generating them in the API itself (ideally controlled by configuration options that can be easily used) or by creating them in your API platform, for example in an API gateway.

Second option

That second option has the advantage that the API does not need to be changed in any way when deprecation or sunset dates become known and should show up in the API. Here is an example of what the Sunset header field looks like in an HTTP API:

Sunset: Wed, 11 Nov 2020 23:59:59 GMT

In addition to the header fields, both specifications also define link relation types, named deprecation and sunset.

These link relation types allow you to make additional information easily findable, such as reasons for deprecation/sunsetting and potential replacements.

Once again, this kind of information helps consumers of the API and making it available therefore is a good practice for API DX.

If you want to learn more about API deprecation and sunsetting, check out the following video. It is the fourth video in a series about “API versioning.”

• The first video explaining “Semantic Versioning.”
• The second one being about “Managing API Versions.”
• The third one discussing how to “Design APIs for Extensibility.”