API Lifecycle Management

Table of Contents

• General
• Important aspect
• Deprecation and Sunsetting
• Implementation
• Best practice

---

General

Qilin.Cloud APIs go through lifecycle like all products, technologies and platforms. They get created, see some usage, get improved over time based on you feedback and product management and sometimes -eventually- they will be discontinued. This may either be the case because an improved (but different) API -or at least a new version- is available, or it simply may not make sense anymore to distribute the API.

Important aspect

An important aspect of Developer Experience (DX) of an API 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.

Deprecation and Sunsetting

Looking at Qilin.Cloud APIs there are two useful pieces of information that are used in our APIs:

• 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 API is available, and consumers are encouraged to switch to that newer version. See RFC Draft: Deprecation Header for more details.
• 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. See RFC 8594: Sunset Header for more details.

Implementation

The mechanisms presented here are easy to use. Qilin.Cloud APIs will integrate 2 Header fields in every result:

If this is the newest version of the API

Header-Key	Value
deprecation	null
sunset	null

If there is a newer version of the API (or this API will get discontinued at all)

Header-Key	Value
deprecation	2023-06-21T13:45:09.5983972Z
sunset	2023-12-31T23:59:59.9999999Z

Best practice

We suggest to use this information in you application and inform the user about deprecation and sunset date in the UI of your application and also send yourself a warning, that there is a newer API version which needs to be implementend till sunset-header-value.