Version deprecation¶

APIs that teams have replaced with newer versions or APIs that are no longer meeting technical, business, or security objectives should be deprecated and eventually deactivated.

The goal of deprecation is to progress to a state where no consumers use the API version. To get to this state, the API team must provide clear, timely, detailed documentation, and communication to consumers. In addition, the API team must do consistent monitoring of the API's usage to ensure consumers are migrating away.

Once it has been determined that an API version should be deprecated:

Establish a sunset period.
Update the API to return Deprecation and Sunset response headers.
Begin deprecation communication and guidance with all consumers to highlight the deactivation date so they can migrate and know the timeframe for completing it.
Stop onboarding new consumers to the deprecated API.
Monitor API usage.

For versioning APIs, direct consumers to the newest version.

For removals of an entire API, clarify that the API is going away and suggest alternate solutions if they are available.

Requirement

Once an API is deprecated, it must no longer onboard new consumers.
API teams must have a plan for communicating the API's deprecation state and deactivation date to all API consumers.

Guidance

The previous API version should enter a deprecated state once a new version of the API is released.
Once an API is deprecated, its documentation should suggest alternate solutions if they are available.

Sunset period¶

The sunset period is the time between marking an API version deprecated and before deactivating it. When determining how long this period should be, it's important to remember that consumers often have different priorities, budgets, and release schedules and may need a long runway to migrate away from a deprecated API. In addition, some consumers may be supporting mobile applications and unable to control when users update a consuming application.

We recommend that API teams keep an API version in a deprecated state for at least 6 months, but not longer than 24 months before deactivation. This allows consumers adequate time to move away from using it and avoids the API team from "permanently" maintaining a deprecated API while also providing motivation for consumers to migrate.

Guidance

API teams must define a sunset period for the API version they are deprecating. At least 6 months is recommended.
API teams should deactivate the API version within 24 months from when marked as deprecated.
API teams may extend the sunset period but should not reduce it unless certain that no consumers depend on the API version in a production environment.
API teams should monitor the deprecated API version to ensure its consumers are migrating away during the sunset period.

HTTP headers used in deprecation¶

API teams must return Deprecation and Sunset response headers in the deprecated API. These headers inform API clients (many of which have built-in deprecation notifications) that the API is no longer supported and the date it will be deactivated.

Requirement

API teams must return Deprecation and Sunset headers in a deprecated API's responses.

Deprecation header¶

The Deprecation header marks an API version as deprecated and slated for deactivation at a future date. Use a boolean true value to set the API version as actively deprecated.

Deprecation: true

Sunset header¶

The Sunset header always takes an HTTP-date timestamp and represents the date an API team will deactivate the API version.

Deprecation: true
Sunset: Thu, 11 Nov 2049 23:59:59 UTC