API-deprecation¶
This document describes the API deprecation strategy for MAJORITY backend API's.
Technical Communication¶
Any API follows a natural life-cycle, from creation to deprecation. We communicate these events to consumers by using HTTP headers. HTTP offers both Deprecation and Sunset header fields for example:
- Sunset: Sat, 25 Aug 2020 23:59:59 GMT
- Deprecation: Sat, 1 Aug 2020 23:59:59 GMT
Usage¶
To deprecate an endpoint decorate it with the [Deprecated] attribute found in Majority.Platform.Deprecation.Contract.
[Deprecated("Use v2..", "2021-10-01")]
[HttpGet("cards)]
Task<ICollection<Card>> Get();
Properties¶
- Message (string): Used to communicate replacement endpoint (required).
- SunsetDate (string yyyy-mm-dd): This is the date when sunset ends (optional).
- DeprecationDate (string yyyy-mm-dd): This is the date when deprecation starts (required).
- LocalizationKey (string). Used to provide a user friendly error message in the exception (optional).
Sunset days¶
We want to keep a consistent sunset length and therefore it's automatically calculated by adding n days from global-deprecation-config to DeprecationDate. A developer can choose to override the global settings when needed by providing a custom SunsetDate.
The configuration file is a platform wide standard per environment, meaning that we can use a different sunset length in production compared to stage environment.
Deprecation¶
When an API is deprecated, this means an API is not usable in its current form for the purpose intended. This usually means that a new version has been created. Consumers should move to new advertised endpoint.
Glossary¶
Sunset¶
Period of time leading up to a deprecation. Endpoints will respond with HTTP status code 410 (GONE) together with a specific error id 508EB235-84CC-4298-A498-2A5D6DE1875B once sunset date has passed.
Deprecation¶
Consumers should move to new endpoint. API will become unusable in future.
Sunset days¶
Number of days for sunset phase before API becomes unusable.