Retire an API endpoint gracefully with Deprecation and Sunset
Short answer: When you plan to retire an API endpoint or version that customers or partners still call, announce it in the responses themselves as well as by email. Add a Deprecation header (RFC 9745) to say the endpoint is deprecated, a Sunset header (RFC 8594) with the date it will stop responding, and a Link header pointing to a migration guide. Track which API keys still call it, contact those owners directly, and only switch it off on the published date.
Why retiring endpoints goes badly
Small SaaS businesses and app makers change their APIs as products grow. An old endpoint returns data in an awkward shape, a version has security issues, or keeping two versions alive costs too much. The usual retirement process is an email to "all developers" and a blog post. Then the endpoint is switched off and a partner's integration breaks, because the email went to someone who left, or the integration was built by a contractor nobody remembers.
A response header can't be missed by the software itself. Monitoring, logs and client libraries can see it on every call, long before the shutdown date.
The Deprecation header
RFC 9745 defines the Deprecation response header. It signals that the resource identified by the response will be or has been deprecated. Its value is a date, written as an @ followed by a Unix timestamp; the RFC's own example is Deprecation: @1688169599, meaning deprecated as of 30 June 2023 at 23:59:59 UTC.
The same RFC defines a deprecation link relation, used in a Link header to point to a page with more information about the deprecation, such as what to use instead and how to migrate.
Deprecation means "still works, but stop relying on it". It doesn't by itself say when the endpoint will stop working.
The Sunset header
RFC 8594 defines the Sunset header, which tells clients that a resource is expected to become unresponsive at a specific point in time, so they can plan their usage. Its value is an HTTP date, such as Sunset: Wed, 30 Jun 2027 23:59:59 GMT, and the RFC says it should be in the future.
Together, the two headers tell a story: "this endpoint is deprecated as of this date, and it will be switched off on that one, and here's the guide".
A sensible retirement plan
- Decide the replacement and the timeline. Give integrators enough time to change code, test and release. Mobile apps need longer, because old versions stay installed.
- Write the migration guide with side-by-side examples of old and new requests.
- Start sending the headers on every response from the old endpoint:
Deprecationwith today's date,Sunsetwith the shutdown date, andLinkto the guide. - Update your API documentation to mark the endpoint deprecated, with the same dates.
- Measure usage per API key or client. Your logs tell you exactly who still calls the endpoint.
- Contact remaining users directly, account by account, with their own call volumes. That's far more effective than a general announcement.
- Send reminders at agreed points before the sunset date.
- Consider brownouts shortly before the date: short, announced windows where the old endpoint returns an error, so forgotten integrations surface while there's still time.
- Switch it off on the date, and return a clear error, for example a 410 Gone with a link to the guide, rather than a generic 404.
What a response looks like
During the notice period, a successful call to the old endpoint still returns its normal data, with three extra headers alongside the usual ones:
Deprecation: @1793404800, the moment you deprecated it.Sunset: Fri, 30 Jul 2027 23:59:59 GMT, the planned shutdown.Link: <https://developers.example.com/migrate-quotes>; rel="deprecation", the guide.
The dates here are illustrative. Keep the values identical across every response from that endpoint, and don't change them without telling integrators, because some teams will put the date into their own planning and alerts.
Helping clients notice
Headers only help if someone reads them. Make it easy:
- Your own SDKs can log a warning when they see a
Deprecationheader. - Suggest to integrators that they log or alert on these headers in their HTTP clients.
- Show a notice in the developer dashboard for any key that called a deprecated endpoint recently.
What not to do
- Changing behaviour silently in an existing version, rather than introducing a new version and deprecating the old one.
- Moving the sunset date earlier after announcing it.
- Shutting down without checking usage in the final week.
- Leaving the deprecated endpoint undocumented, so new customers keep adopting it.
Versioned APIs
If you version your API in the URL or a header, the same headers apply to a whole version: every response from version 1 can carry them once version 2 is the recommended path. Keep the old version's behaviour stable until the sunset date; a deprecated version that keeps changing defeats the purpose.
A worked example
Consider a hypothetical Christchurch freight-booking platform that wanted to retire an old quote endpoint used by several logistics partners. It published a migration guide, added Deprecation, Sunset and Link headers to every response, and marked the endpoint in its documentation. Logs showed four partner accounts still calling it two months later. The team emailed each partner's technical contact with their own call counts, ran two short brownouts in the final month, and switched the endpoint off on the published date with a helpful 410 response. No partner was caught by surprise.
FAQ
Do clients automatically act on these headers?
Usually not. They're signals for developers and tools. Pair them with direct communication.
Can I use Sunset without Deprecation?
Yes. Each header stands alone, but together they're clearer.
How long should the notice period be?
Long enough for your slowest integrator to change and release. Many businesses choose several months for partner APIs.
Should I keep the guide link after shutdown?
Yes. Errors from the retired endpoint should point to it.
If you need to retire parts of your API without breaking customers, tell us how your API is used and we'll help plan it.