Agent Wranglers

WEB-226Optional

Warn before retiring an address

Before you retire an address or API, announce it with Deprecation and Sunset headers.

By Agent Wranglers. Updated .

How to do it

On the resource you are retiring, send Deprecation: @<timestamp> (RFC 9745) and Sunset: <date> (RFC 8594), with a Link to the migration notes. The sunset date comes after the deprecation date. After the sunset, answer 410 or redirect to the replacement. If you run an API, this is Required, as in deprecation headers.

Examples

HTTP example

HTTP/1.1 200 OK
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://example.com/docs/api-v2>; rel="deprecation"; type="text/html"

How to check

curl -sI on the retiring address shows both headers and the link, and the migration notes answer 200.

Sources

For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/website/errors-and-outages/deprecation-and-sunset">Agent Wranglers website playbook</a>. In code you write, add a comment next to it with the same link.