Summary

  • RFC 9745, published in March 2025, defined a Deprecation response field containing a Structured Field Date. The date says when the resource was or will be deprecated; the resource can continue to behave as before.
  • A Link relation named deprecation can point to policy or migration documentation, even before the field appears. A separate 2019 Sunset field says when the resource is expected to become unresponsive.
  • The operator decides the notice date and the scope it publishes. Clients receive a planning signal, not a guaranteed shutdown schedule. Dated response captures would show where the new field actually ran.

The machine keeps answering after the notice

Many service endings begin while the service is visibly healthy. An API returns data, accepts requests, and passes ordinary availability checks. Its operator wants new clients to choose another interface and existing clients to prepare a move. If the only machine-readable notice arrives when the endpoint fails, every dependent application discovers the transition at the worst possible moment. If the notice is buried in a human policy page, a client developer may never see it while watching actual traffic.

RFC 9745 put the notice into the HTTP response itself. The Deprecation field describes the resource identified by that response. Its value is a date in the Structured Fields syntax, shown in the specification as Deprecation: @1688169599. The example date is 30 June 2023 at 23:59:59 UTC. A date in the future says deprecation will take effect then; a date in the past says it has already taken effect. The field gives a lifecycle statement to a resource that can still answer the request normally.

That last point is the whole sting. RFC 9745 says deprecation itself leaves the resource's behavior unchanged. A working response and a warning can occupy the same packet. The operator can say “please leave” while continuing to serve the clients already inside. For a client team, that is a real scheduling problem. Continuing to use the endpoint may work today, but writing a new long-lived dependency against it piles up future migration work.

The header is tied to the response's resource. A provider may wish to retire a whole API or a set of endpoints, but the meaning of a notice on one endpoint does not automatically spread to every neighbor. RFC 9745 says an API can define rules for broader scope. Someone must publish those rules. Without them, a client inspecting one response has evidence about that response's resource, not a map of the whole service.

The manual can arrive before the alarm

The 2025 RFC also registered a deprecation link relation. A server may include a Link field pointing to documentation about migration, replacement, or deprecation policy. The link can appear before the Deprecation field, so developers can learn how the operator plans to warn them before a particular resource is formally deprecated. The standard even gives the asymmetry an explicit example: a documentation link is present, the date field is absent, and the resource is not yet deprecated.

This division matters because a date alone gives poor instructions. A client can put a timestamp in a dashboard but still needs to know what replaces the resource, which paths are covered, and whether a migration changes data or permissions. Documentation can answer those questions. The Link relation makes the operator's chosen explanation discoverable from the running interface. It does not write a migration plan by itself. The quality of that plan remains the operator's work.

There is an institutional choice hidden in the pairing. The server owner controls which page the response points to and when the date appears. The client developer sees a notice in live traffic, then decides how much engineering time to assign to the move. The standard makes the notice interoperable; it does not distribute the migration bill evenly.

Deprecation has one clock; Sunset has another

HTTP already had a related notice. RFC 8594, published in May 2019, defined Sunset to communicate when a resource is expected to become unresponsive. It uses an HTTP-date, like Sunset: Sun, 30 Jun 2024 23:59:59 UTC. Deprecation addresses a different moment: the resource is no longer recommended for continued dependence, even while it works. The two dates answer separate questions. When should clients stop treating this resource as the future? When might it stop answering at all?

RFC 9745 lets a provider send both fields and requires the Sunset timestamp to be no earlier than the Deprecation timestamp. Its example puts deprecation on 30 June 2023 and sunset a year later. A reversal would be a broken plan on the wire: the operator would be promising retirement after expected unavailability. The format difference is visible too. Deprecation uses a Structured Field Date marked with @; Sunset retains the older HTTP-date spelling.

Neither clock is a mechanical power switch. RFC 8594 presents Sunset as an expected future condition; RFC 9745 describes Deprecation as a hint about lifecycle status. A service could close earlier, later, or under different routing behavior. The dates matter because clients need a planning horizon. Their usefulness depends on the provider keeping its schedule intelligible and its replacement path usable.

The warning is carried by the thing it warns about

The 2025 field did not invent retirement. It changed where a provider can make a retirement claim and how clients can encounter it. The notice now rides with the resource during normal use, before a failure proves that maintenance is urgent. The provider's control over the response gives it an efficient channel to reach its dependencies. It also gives it the power to set a migration deadline while other organizations pay for the change.

The published RFC proves the design, not its deployment. Dated responses from named services and dated client releases would establish actual adoption. The historical point is already sharp: HTTP gained a way for a fully functioning API to tell the next generation of clients to leave. The most consequential message in a successful response may be the deadline attached to it.