RFC 9745

The Deprecation HTTP Response Header Field

📅 published March 2025, from ietf

RFC 9745: The Deprecation HTTP Response Header Field 🎀

Okay bestie, this is RFC 9745, and it's giving Standards Track 💅 It's an IETF document from March 2025 (ISSN 2070-1721), written by S. Dalal and E. Wilde. It's a proper Internet Standards Track doc, so the IETF community reviewed it and it's officially approved. The title block doesn't say it obsoletes or updates anything, so nothing to clean up there 🙈

Abstract ✨

So the Deprecation HTTP response header field tells consumers of a resource (the thing you identify with a URI) that the resource will be or has been deprecated 🧚 There's also a deprecation link relation that can point to a resource with more info about planned or existing deprecation. It can also show client app devs the best ways to handle deprecation. Main character energy 👑

Status of This Memo 📜

This is an Internet Standards Track document 🦋

It's a product of the Internet Engineering Task Force (IETF), and it represents the consensus of the IETF community. It got public review and was approved for publication by the Internet Engineering Steering Group (IESG). If you want more on Internet Standards, check out Section 2 of RFC 7841 🌸

For the current status, any errata, and how to send feedback, go to https://www.rfc-editor.org/info/rfc9745 ✨

Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved 💜

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) as they stand on the date of publication. Please actually read these, bestie, because they explain your rights and restrictions for this doc 🫶

Code Components pulled out of this document must include Revised BSD License text, as described in Section 4.e of the Trust Legal Provisions. They're provided without warranty, as described in the Revised BSD License 🔥

Table of Contents 🗂️

1.  Introduction
  1.1.  Notational Conventions
2.  The Deprecation HTTP Response Header Field
  2.1.  Syntax
  2.2.  Scope
3.  The Deprecation Link Relation Type
  3.1.  Documentation
4.  Sunset
5.  Resource Behavior
6.  IANA Considerations
  6.1.  The Deprecation HTTP Response Header Field
  6.2.  The Deprecation Link Relation Type
7.  Security Considerations
8.  Normative References
Acknowledgments
Authors' Addresses

1. Introduction 🌈

Okay so deprecating an HTTP resource (see Section 3.1 of [HTTP]) is all about its lifecycle. It nudges client apps to migrate away from the resource, discourages them from building new dependencies on it, and warns them about the risk of hanging on to it 💀

Deprecating doesn't change how the resource behaves at all 🙅‍♀️ It just tells client apps that the resource will be or has been deprecated. The Deprecation HTTP response header field can pass that info along at runtime and say when the deprecation kicks in ✨

Besides the Deprecation header field, the resource provider can use other header fields, like the Link header field [LINK], to share more deprecation info 🍓 Think docs about the deprecation, what to use instead, and when the deprecated resource stops working for good.

1.1. Notational Conventions

Here's the lowkey important part 🙈 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 💖

This doc also uses "Structured Field Values for HTTP" [RFC9651] to spell out syntax and parsing for date values 📅

And "resource" has the meaning from Section 3.1 of [HTTP] 🦋

2. The Deprecation HTTP Response Header Field 💜

The Deprecation HTTP response header field lets a server tell a client app that the resource in the context of the message will be or has been deprecated 🧚

2.1. Syntax

The Deprecation header field describes the deprecation of the resource identified with the response it showed up in (see Section 6.4.2 of [HTTP]). It carries the deprecation date, which can be in the future (the resource in context will be deprecated then) or in the past (the resource in context was deprecated then) ⏳

Deprecation is an Item Structured Header Field, and its value MUST be a Date as per Section 3.3.7 of [RFC9651] 💅

Here's an example showing the resource in context was deprecated on Friday, June 30, 2023 at 23:59:59 UTC:

Deprecation: @1688169599

2.2. Scope

The Deprecation header field applies to the resource identified with the response it showed up in (see Section 6.4.2 of [HTTP]). So it announces the upcoming deprecation of that specific resource 🎀 BUT, and this is a big but, the scope of the announced deprecation can sometimes be bigger than just the one resource where the header shows up 👀

Resources are free to define a bigger scope, and usually they document it so consumers know about it and can act accordingly 📚 Here's the tea: that bigger scope is invisible to consumers who don't know about the extra scoping rules. Those consumers won't know the scope is bigger, and they'll read the deprecation info with its standard meaning (it applies to the resource only) 🙈

Using a bigger scope can still make sense, because deprecation info is only a hint anyway 💡 It's optional info that you can't rely on, so client apps should always be built to work without it 🫶 Extra scope info can help devs pick up hints from related resources, which can let them make educated guesses about which resources are about to get deprecated 🔮

For example, an API might only put Deprecation header fields on designated resources, like its home document, and not on every single resource 🏠 Then the deprecation info is available, but devs have to keep checking the home document to get it. In that case, the extended context of the Deprecation header field is all resources the API provides, while the info is only visible on the home document ✨

Besides the Deprecation HTTP response header field, the server can use links with the deprecation link relation type to tell client app devs where to find more info about deprecating the context 📍 That can happen before the actual deprecation, so the deprecation policy is discoverable, or after it, when there might be docs about the deprecation and how to manage it 💖

This spec puts no restrictions on how the linked deprecation policy is represented 🌸 The policy could be human-readable docs or a machine-readable description. Your call, bestie ✨

3.1. Documentation

The whole point of the Deprecation header field is to give the resource consumer a hint about deprecation 🎀 When a client app dev gets the Deprecation header field, they can look up the resource's documentation to find deprecation info. The documentation MAY include a guide and timeline for moving off the deprecated resource to new resource(s) that replace it, if that applies 🗺️ The resource provider can link to the docs using a Link header field with the relation type deprecation, like this:

Link: <https://developer.example.com/deprecation>;
      rel="deprecation"; type="text/html"

In this example, the linked content gives extra info about deprecation of the resource in context. There's no Deprecation header field in the response, so the resource isn't (yet) deprecated. But the resource already has a link showing how deprecation is managed for it 🔍 That could be docs explaining when deprecation might happen and what the deprecation policies are. For example, a policy might say deprecation of resource(s) will always be signaled in dedicated places at least N days before the planned date, and then the resource(s) get deprecated on that date ⏰ Or a policy might say the resource(s) get deprecated first and only then get signaled as deprecated in dedicated places 🙃 The docs can also include a migration guide that explains how to move to a new or alternate resource(s) before the deprecation date. Policy and docs like this are super useful for consumers who want to plan ahead and migrate smoothly 💅

Here's the same Link header field, but now there's also a deprecation date using a Deprecation header field:

Deprecation: @1688169599
Link: <https://developer.example.com/deprecation>;
      rel="deprecation"; type="text/html"

Since the deprecation date is in the past, the linked info resource may have been updated to include info about the deprecation 📖 That lets consumers find out about the deprecation and figure out how to handle it best 🫶

4. Sunset 🌅

Okay so beyond deprecation info, if the resource provider wants to tell the client app that the deprecated resource is expected to stop responding at a specific point in time, they can use the Sunset HTTP header field [RFC8594] alongside the Deprecation header field 🌇

The timestamp in the Sunset HTTP header field MUST NOT be earlier than the one in the Deprecation header field 🚫 If that happens (say, a deployment misconfiguration or some other error), the client app developer SHOULD consult the resource developer to get clarification 📞

Here's an example showing the resource in context was deprecated on Friday, June 30, 2023 at 23:59:59 UTC, with a sunset date of Sunday, June 30, 2024 at 23:59:59 UTC 🗓️ Heads up, bestie: for historical reasons, the Sunset HTTP header field uses a different date format ⚠️

Deprecation: @1688169599
Sunset: Sun, 30 Jun 2024 23:59:59 UTC

5. Resource Behavior 🎭

Deprecating doesn't change any behavior of the resource 🙅‍♀️ Seeing a Deprecation header field in a response isn't meant to signal any change in the meaning or function of the resource in context. Consumers can keep using the resource the same way they did before it got declared deprecated 💖

6. IANA Considerations 📋

More of the story is coming in part 2, bestie 🦋

6.1. The Deprecation HTTP Response Header Field

okay so the Deprecation header field got added to the "Hypertext Transfer Protocol (HTTP) Field Name Registry" (Section 16.3.1 of [HTTP]) 🎀 Here's its entry:

Field Name:  Deprecation

Status:  permanent

Structured Type:  Item

Reference:  RFC 9745, Section 2: The Deprecation HTTP Response Header
   Field

the deprecation link relation type got added to the "Link Relation Types" registry (Section 4.2 of [LINK]) 💅 Here's the entry:

Relation Name:  deprecation

Description:  Refers to documentation (intended for human
   consumption) about the deprecation of the link's context.

Reference:  RFC 9745, Section 3

7. Security Considerations 🔐

okay bestie, this part is seriously important 😭 so pay attention!!

The Deprecation header field should be treated as a hint 💭 It means the resource is indicating (but not guaranteeing with certainty) that it will be or has been deprecated. Deprecated resources keep working the way they would have without the Deprecation header field. The non-functional stuff can change, though 🙈 For example, they might have less efficiency and longer response times.

The resource's documentation should give more info about the deprecation, like recommendations for a replacement ✨ Developers of client applications that consume the resource SHOULD always check the referred resource's documentation to verify authenticity and accuracy. Main character energy: verify everything 💅 When a Link header field is used to provide documentation, one should assume (unless it's served over HTTPS) that the Link header field's content may not be secure, private, or integrity-guaranteed. So be super careful with it (see Section 5 of [LINK] for more details) 🫶

🚨 If the Deprecation header field value is in the past, client application developers MUST no longer assume that the resource behaves the way it did before the deprecation date. Don't be the person who assumes nothing changed 💀

If the Deprecation header field value is a date in the future, it tells client application developers when the deprecation takes effect 🦋 So client application developers consuming the resource SHOULD, if possible, consult the resource developer about the potential impact of the deprecation, and plan for a possible transition to a recommended resource or resources. Planning ahead is so iconic 👑

8. Normative References 📚

Acknowledgments 🫶

the authors wanna give a huge thank you to Nikhil Kolekar, Darrel Miller, Mark Nottingham, and Roberto Polli for their contributions 💖

the authors take all responsibility for errors and omissions 🙈

Authors' Addresses 🎀

Sanjay Dalal
Email: sanjay.dalal@cal.berkeley.edu
URI:   https://github.com/sdatspun2


Erik Wilde
Email: erik.wilde@dret.net
URI:   http://dret.net/netdret
📦 where this page comes from