API Deprecation

From time to time, we may need to deprecate API endpoints as our APIs evolve. When an endpoint is deprecated, we may communicate this through standard HTTP response headers in accordance with RFC 9745 (Deprecation) and RFC 8594 (Sunset).

We recommend that integrations monitor API responses for these headers so that deprecations can be detected automatically and action can be taken before an endpoint is removed.

Detecting a deprecated endpoint

Our deprecations may have a removal date without a recorded date for when the deprecation started. As a result, you will typically see a Sunset header, sometimes alongside a Link header if a successor endpoint is available, without a Deprecation header.

The three headers are independently optional. An endpoint may therefore have any combination of these headers, or none at all. For example, an endpoint may be marked as deprecated without having a deprecation or removal date confirmed yet.

1. Deprecation date, removal date and successor endpoint

HTTP/2 200
deprecation: @1759276800
sunset: Wed, 01 Oct 2026 00:00:00 GMT
link: <api/booster-sample-lambda-proxy/todoitems/{id}/v2>; rel="successor-version"

2. Removal date known, no successor tracked

HTTP/2 200
sunset: Thu, 31 Dec 2099 00:00:00 GMT

3. Removal date and successor endpoint

HTTP/2 404 sunset: Thu, 31 Dec 2099 00:00:00 GMT link: <api/booster-sample-lambda-proxy/todoitems/{id}/v2>; rel="successor-version"

4. Deprecation date passed

HTTP/2 404 deprecation: @1767225600

Deprecation

RFC 9745 (formerly draft-ietf-httpapi-deprecation-header)
The Deprecation header indicates that the endpoint has been deprecated. Its value is expressed as a Unix timestamp.

Sunset

RFC 8594
The Sunset header indicates when the endpoint is expected to stop working. Its value is expressed as an HTTP-date

Your service should monitor for these headers and use them to trigger your internal process for reviewing and updating integrations.

Successor Version

RFC 5829
Where a replacement endpoint is available, the response will also include a Link header with rel="successor-version" ipointing to the replacement endpoint.

API Reference

We will also update the API Reference to reflect the current status of endpoints.

Example of a deprecated notice in the API reference.

When an endpoint is deprecated, its status will be clearly indicated in the API Reference documentation, along with any relevant information about its replacement or removal timeline.

We recommend using both mechanisms:

1. Monitor the Deprecation and Sunset response headers in your integration for automated detection.
2. Check the API Reference for additional information about deprecated endpoints, replacements and timelines.

Monitoring the response headers allows your service to detect changes automatically, while the API Reference provides the wider context needed to plan and implement any required changes.

For more information, see ⁠RFC 9745 for the Deprecation header and ⁠RFC 8594 for the Sunset header.