# A standard HTTP header to say an API is deprecated (RFC 9745)
Table of Contents
Anyone who maintains an API eventually has to retire something: an address that’s answered for years, a response format, a whole version of the service. The hard part isn’t technical, it’s communication. How do you warn the people using that API that it’s about to disappear, without hoping someone reads the right email or the right note in the changelog? In March 2025 the IETF, the body that maintains Internet’s technical standards, published RFC 9745 and turned a simple answer into a standard: the HTTP Deprecation response header, one of many updates through which the IETF is expanding the protocol, alongside for instance the new HTTP QUERY method.
The problem: warning machines, not just people
A little vocabulary first, because it helps. An API is the interface two programs use to talk to each other over the network. An endpoint is one of the addresses that API exposes. A header is a line of service information attached to every HTTP request and response, kept separate from the actual content. And to deprecate a resource means declaring it still working but on its way out: you can use it, but you’d better stop and move to something else.
Until now, deprecation has almost always been announced in words: a blog post, an entry in the docs, an email to developers. That’s fine for people, but not for software. A program calling an API a thousand times a day doesn’t read the blog. It keeps hitting that endpoint until one day it stops answering, and at that point it’s a production outage. What’s missing is a way for the response itself to say, in a form a computer can read: “heads up, this resource is being retired.”
That’s exactly the gap RFC 9745 sets out to fill.
What RFC 9745 is
RFC 9745 is titled The Deprecation HTTP Response Header Field and was published in March 2025 by the IETF, with Sanjay Dalal and Erik Wilde as authors. It defines a new response header, Deprecation, with which a server signals to consumers of a resource that the resource will be, or has already been, deprecated.
The mechanism is deliberately minimal. The server adds one line to its HTTP responses, and whoever receives them - a client, a monitoring tool, a library - can read it automatically. No change to the content, nothing breaks: just one extra signal.
How you write it: a date, and that’s it
The header’s value is a date, expressed in the format of HTTP Structured Fields (RFC 9651), the standard that defines how to write structured values inside headers so everyone reads them the same way. In practice the date is written as a Unix timestamp - the number of seconds elapsed since 1 January 1970 - prefixed with an at-sign. An example from the specification:
Deprecation: @1688169599That number corresponds to 30 June 2023 at 23:59:59 UTC. The interesting bit is that the date can be in the future or in the past. In the future it means “this resource will be deprecated from that moment on”: advance notice. In the past it means “it’s already been deprecated since then”. With a single line the server conveys both the intent and the accomplished fact.
Deprecated doesn’t mean switched off
There’s a common misunderstanding to clear up here, and the RFC is explicit about it. Deprecating a resource does not change its behaviour. A deprecated endpoint keeps working as before: it answers, it returns the same data, it doesn’t change meaning. The header’s presence isn’t an error and doesn’t force you to stop using it right away. It’s a notice, not a closed door.
Deprecation and retirement are two distinct moments. Deprecation says “start moving”; retirement (the sunset) is the day the resource actually stops answering. Between the two there is, or should be, time to migrate.
Its natural companion: the Sunset header
To name that day there’s another standard header, Sunset, defined by RFC 8594. Where Deprecation says “deprecated from when”, Sunset says “stops working from when”. The two pair up nicely, and RFC 9745 adds a common-sense rule: the Sunset date must not be earlier than the Deprecation date. It would make no sense to switch a resource off before you’ve even declared it on its way out.
Saying what to use instead: the “deprecation” relation
A date on its own doesn’t tell the whole story. It doesn’t explain why the resource is being retired, what to use instead, or by when to finish the switch. That’s why RFC 9745 also defines a link relation called deprecation: a standard way to link, again via a header, to a documentation page that holds the rest of the story. The specification’s example is this:
Deprecation: @1688169599Link: <https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"The Link header points to an address, and rel="deprecation" declares that this link is about the retirement itself. There the API provider can describe the deprecation policy, the timeline and - where one exists - the resource that replaces the old one, with a migration guide. The documentation can even set a clear rule, for instance that every deprecation will be announced a given number of days ahead of the switch-off date.
Why it matters for an API’s lifecycle
The value of all this isn’t the header itself, but the fact that a retirement notice is finally machine-readable, the same principle behind other HTTP signals built for automated clients, like the one that lets sites charge AI crawlers. That changes several practical things.
- A client can notice on its own that it’s calling a deprecated endpoint and write it into its own logs, instead of finding out on the day the endpoint dies.
- A monitoring tool can inspect responses and raise an alert when the header shows up, giving the team time to react.
- Anyone consuming dozens of different APIs can measure how much “debt” they’ve built up - how many dependencies are about to vanish - without chasing changelogs written differently by each provider.
In a word, managing an API’s lifecycle stops depending on whether a person read the right message at the right time. The signal travels alongside the data.
Where it stands
A note on status, because it’s easy to misread. RFC 9745 is a Proposed Standard: not a draft, not an experimental document, but the first stable rung on the IETF standards track, the same level reached by the HTTP Concealed authentication scheme too. It means the text is mature, publicly reviewed and citable, and that the Deprecation header has been registered permanently in the official HTTP field name registry. From here on, anyone designing APIs can adopt it knowing the meaning is fixed once and for all.
What remains is adoption, which is up to individual providers: the header’s value shows only when servers send it and clients read it. But the hard part - agreeing on a single, sensible format - is done. For anyone maintaining APIs, adding a Deprecation header (and ideally a Sunset one and a link to the docs) is a small gesture that makes a retirement far less painful for the people on the other side.
