API Deprecation and the Sunset Header

Deleting an endpoint takes a minute and somebody else pays for it. Deprecating one is the alternative, and it works only if it is a dated plan with a migration path rather than a note in a changelog.

Announcement, grace, sunset, removal

Every workable deprecation has the same four stages, whatever you call them internally.

Announcement. The change becomes public with an end date attached. Nothing behaves differently yet, and consumers can plan.

Grace period. The window in which migration is expected. Both the old and the new path work, and the old one is signalling that it is on the way out.

Sunset phase. The last stretch before the date. This is where escalating signals belong, since anybody still calling at this point has not seen the earlier ones.

Removal. The endpoint stops answering. That the date arrived and that you are ready are two different statements, and only one of them should come from a timer.

V1V2Deprecation:Sunset:GRACE PERIODANNOUNCEDSUNSETREMOVEDsunset can never precede deprecation

The number that matters most is the gap between the announcement and the sunset. Ninety days is a common floor for public APIs, and enterprise or regulated consumers routinely need six months, because their release process runs on quarters. Set the date once and never move it closer, since a shortened deprecation teaches consumers that your dates are negotiable.

The headers, with their sources

Two HTTP headers carry this in-band, so a consumer's own monitoring can find out without anybody reading an email.

Deprecation is standardised in RFC 9745, published in March 2025 on the standards track. It carries a structured field date saying when the resource became, or will become, deprecated. Sunset comes from RFC 8594, published in May 2019 as informational, and it carries an HTTP date for when the resource is expected to become unresponsive. The two are designed to be used together, and RFC 9745 states that the sunset timestamp cannot be earlier than the deprecation timestamp.

RFC 8594 also registers a sunset link relation, which is the right way to point at the page explaining the retirement. A response carrying both headers and a link to a migration guide tells a machine and a person everything they need.

One header to leave alone is Warning. It was the older way to attach a human-readable note to a response, and RFC 9111 obsoletes it, stating that it is not widely generated or surfaced to users. If you send it, send it as an extra on top of the two headers above and never as the only signal.

Escalation that respects the calendar

The point of a phased retirement is that the signal grows while the consequence stays deferred. A workable escalation looks like this.

Stage	What the consumer experiences
Announcement	Deprecation and Sunset headers, changelog entry, portal banner
Grace period	The same headers, plus scheduled reminders as the date approaches
Sunset phase	Stronger signals, and in testing environments a preview of the removal
After sunset	410 Gone, which says the resource existed and is intentionally gone

410 rather than 404 is worth the extra thought. A 404 reads as a mistake in the caller's URL and sends a developer looking for a typo, while a 410 says the resource is deliberately gone and sends them looking for the migration guide.

Practising the removal in a non-production environment before the date is the single most effective step in this list. A consumer who hits the removal in their own test run has time to react, while one who hits it in production does not.

The migration guide is the deliverable

Everything else is scaffolding around one artefact, which is the text a consumer reads at the moment they discover the problem.

A useful migration guide names the replacement, shows the old call and the new call side by side, states what changed about the response, and describes anything that has no equivalent. That last part is the one people skip and the one that matters, because a consumer who cannot find the replacement for a field assumes the migration is impossible and escalates.

Where there is no replacement, say so plainly and explain why the capability is going away. That is a harder message and a shorter conversation than letting them search.

Tell the people who are still calling

The final piece is knowing whether anyone is listening. Usage data for a deprecated endpoint turns the removal decision from a guess into an observation, and traffic that has been at zero for two weeks is the strongest signal you will get.

Where you have identifiable consumers, a direct message beats a changelog. A team that receives an email naming their integration and the date it stops working will act, while the same information in a release note will not reach them.

In Routebase

A deprecation in Routebase is a dated plan with phases rather than a flag. The wizard asks for the sunset date, the successor endpoint, the migration guide and the sunset policy, and it validates the date against the minimum grace period your organisation set.

Phases advance on their own as their dates come due, with one deliberate exception, since retirement happens automatically only if you asked for it. Consumers see a banner on the portal page with the remaining days, the rendered migration guide and a link to the successor, and your team gets reminders before the date. Against a Routebase mock server the sunset policy also changes behaviour, adding the deprecation warning, reducing the rate limit, and answering 410 Gone during an optional soft-shutdown window so consumers meet the removal in testing first. Organisation-wide presets set the floor for the grace period and can require a migration guide, a successor or an approval. The Deprecation guide covers the phases and the policy in full, and the blog post on versioning without breaking your consumers works through a deprecation end to end.