Retiring a Version With the Deprecation and Sunset Headers

Announce, mark every response, watch who still calls, then switch it off on the date you published.

Retiring an API version means moving every client off it before it is switched off, which takes published dates and a signal clients see on every response. Two standard headers carry that signal: Deprecation, from RFC 9745, says a resource is deprecated and since when, and Sunset, from RFC 8594, says when it will stop responding. A Link header points to the migration guide.

Retiring version 1 of an orders API

Announce the plan

Publish the deprecation date, the sunset date and a migration guide, and tell every registered client directly. Allow months for external clients, not weeks.

Mark every response

From the deprecation date, every v1 response carries Deprecation: @1798761600, the Unix time of 1 January 2027, and Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation".

Publish the sunset date

Add Sunset: Thu, 01 Jul 2027 00:00:00 GMT to the same responses, so clients and their monitoring can see the removal date.

Watch who still calls

Log calls to v1 by client, contact those still calling as the date approaches, and consider brief planned outages, a brownout, to surface clients nobody has heard from.

Switch it off on the date

After the sunset date, answer v1 requests with 410 Gone and a problem details body naming the new version, rather than a 404 that looks like a mistake.

What the headers do and do not do. They let a client's code and monitoring notice deprecation without a person reading an email. They do not move anyone, so the announcement and the usage tracking still matter.

Why 410. 410 Gone, defined in RFC 9110, says the resource existed and was removed on purpose, which a client can tell apart from a typo. Keep answering 410 for a while, so late clients get a clear message.

Keep the date. Moving the sunset date later teaches clients to ignore it; switching off earlier than published breaks the promise the headers made. The values in this walkthrough are illustrative.

← → move through sections and cards