RFC 8594

The Sunset HTTP Header Field

📅 published May 2019, from ietf

The Sunset HTTP Header Field 🌸

Okay bestie, let's do the paperwork first 📎 This one is RFC 8594, written by E. Wilde and published in May 2019. It's an Informational doc, so it isn't an Internet Standards Track spec. It's here to share info 💅 It's a product of the IETF, with ISSN 2070-1721. The title block doesn't list anything it obsoletes or updates, so it's standing completely on its own ✨

Abstract 🦋

Okay so this spec defines the Sunset HTTP response header field 🎀 It tells you that a URI will probably stop responding at some specific point in the future. It also defines a sunset link relation type, which lets you link to resources with info about an upcoming resource or service sunset. Main character energy for URIs, honestly 😭

Status of This Memo 📜

This document is not an Internet Standards Track specification. It's published for informational purposes 💖

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are candidates for any level of Internet Standard. See Section 2 of RFC 7841 for that 🧐

Info about the current status of this document, any errata, and how to give feedback on it is at https://www.rfc-editor.org/info/rfc8594 🔗

Copyright (c) 2019 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 in effect on the date of publication of this document. Please read these carefully, because they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they are provided without warranty as described in the Simplified BSD License 📝

Table of Contents 🗂️

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
  1.1.  Temporary Resources . . . . . . . . . . . . . . . . . . .   3
  1.2.  Migration . . . . . . . . . . . . . . . . . . . . . . . .   3
  1.3.  Retention . . . . . . . . . . . . . . . . . . . . . . . .   3
  1.4.  Deprecation . . . . . . . . . . . . . . . . . . . . . . .   3
2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
3.  The Sunset HTTP Response Header Field . . . . . . . . . . . .   4
4.  Sunset and Caching  . . . . . . . . . . . . . . . . . . . . .   5
5.  Sunset Scope  . . . . . . . . . . . . . . . . . . . . . . . .   6
6.  The Sunset Link Relation Type . . . . . . . . . . . . . . . .   6
7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
  7.1.  The Sunset Response Header Field  . . . . . . . . . . . .   7
  7.2.  The Sunset Link Relation Type . . . . . . . . . . . . . .   8
8.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
9.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . .   9
10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  10
  10.1.  Normative References . . . . . . . . . . . . . . . . . .  10
  10.2.  Informative References . . . . . . . . . . . . . . . . .  10
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  10
Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  11

1. Introduction 🧚

Okay so the general rule is that URIs should be stable and persistent, so apps can use them as stable identifiers for resources 🫶 But there are lots of situations where, for all kinds of reasons, a URI has a limited lifetime. Sometimes that limited lifetime is known ahead of time. In that case it can be really useful for clients if resources make that info about their limited lifetime known 💜 This spec defines the Sunset HTTP response header field, which says a URI is likely to become unresponsive at a specified point in the future. Iconic 👑

This spec also defines a sunset link relation type. It lets you share info about 1) the sunset policy of a resource or service, and/or 2) upcoming sunsets, and/or 3) possible mitigation scenarios for resource or service users 🎀 It doesn't put any constraints on the nature of the linked resource, so it can be aimed at humans, machines, or both 🤖

Here are some possible scenarios for known lifetimes of resources. This list is not exhaustive 💅

1.1. Temporary Resources 🛍️

Some resources have a limited lifetime by definition. For example, a pending shopping order might already list all of its order details, but it may only exist for a limited time unless it's confirmed. Only then does it become an acknowledged shopping order. In a case like this, the service managing the pending order can make that limited lifetime explicit. That way clients understand that the pending order, unless it's confirmed, will disappear at some point in time 😭

1.2. Migration 🚚

If resources are changing identity because a service migrates them, that may be known in advance. It might not be appropriate to use HTTP redirect status codes (3xx) yet. Even so, it can be interesting for clients to learn about the service's plan to take down the original resource 👀

1.3. Retention 🗄️

There are lots of cases where regulation or legislation requires that resources stay available for a certain amount of time. But in many cases there's also a requirement for those resources to be permanently deleted after some period of time. Since the deletion in this scenario is governed by well-defined rules, it could be made explicit for clients interacting with the resource 🍓

1.4. Deprecation 🥀

For Web APIs, one standard scenario is that an API, or specific subsets of an API, gets deprecated. Deprecation often happens in two stages. In the first stage, the API is no longer the preferred or recommended version. In the second stage, the API or a specific version of it gets decommissioned 💀

For the first stage (the API is no longer the preferred or recommended version), the Sunset header field is not the right fit. At this stage the API is still running and can still be used. Other mechanisms can signal that first stage and help with more visible deprecation management, but the Sunset header field doesn't aim to represent that info 🙅‍♀️

For the second stage (the API or a specific version of it gets decommissioned), the Sunset header field is appropriate. That's when the API or version does become unresponsive. From the Sunset header field's point of view, it doesn't matter that the API may no longer have been the preferred or recommended version. The only thing that matters is that it will become unresponsive, and that this time can be advertised using the Sunset header field ⏰

In this scenario, the announced sunset date typically affects all of the deprecated API or parts of it (that is, just deprecated sets of resources), not just a single resource. So it makes sense for the API to define rules about how an announced sunset on a specific resource (such as the API's home or start resource) implies the sunsetting of the whole API or parts of it (sets of resources). It shouldn't stop at just the resource returning the Sunset header field. Section 5 discusses how the scope of the Sunset header field may change depending on how a resource is using it 🌈

2. Terminology 📖

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 💅 That's the vocab rule, bestie, so keep it in mind 🎀

3. The Sunset HTTP Response Header Field 🌷

The Sunset HTTP response header field lets a server communicate the fact that a resource is expected to become unresponsive at a specific point in time. It gives clients info they can use to control how they use the resource ✨

The Sunset header field contains a single timestamp that advertises the point in time when the resource is expected to become unresponsive. The Sunset value is an HTTP-date timestamp, as defined in Section 7.1.1.1 of [RFC7231], and it SHOULD be a timestamp in the future 🕰️

It's safest to treat timestamps in the past as meaning the present time. That way, the resource is expected to become unavailable at any time 😬

Here's the grammar:

Sunset = HTTP-date

And an example:

Sunset: Sat, 31 Dec 2018 23:59:59 GMT

Clients SHOULD treat Sunset timestamps as hints. It's not guaranteed that the resource will actually be available until that time, or that it won't be available after that time. Still, since the info comes from the resource itself, it has some credibility 🫶

After the Sunset time has arrived, interactions with the resource will likely result in client-side errors (HTTP 4xx status codes), redirect responses (HTTP 3xx status codes), or the client might not be able to interact with the resource at all. The Sunset header field doesn't reveal which of those behaviors to expect 🙈

Clients that don't interpret an existing Sunset header field can operate as usual. They may just experience the resource becoming unavailable without having had any notification about it beforehand 🥲

4. Sunset and Caching 🧁

It's worth noting that the Sunset HTTP response header field serves a different purpose than HTTP caching [RFC7234]. HTTP caching is about making resource representations (that is, represented resource state) reusable, so they can be used more efficiently. It does this with header fields that help clients and intermediaries understand when a representation can be reused, or when resource state (and therefore the representation) may have changed 📦

The Sunset header field isn't concerned with resource state at all. It only signals that a resource is expected to become unavailable at a specific point in time. There are no assumptions about if, when, or how often a resource may change state in the meantime 🌙

So the Sunset header field and HTTP caching should be seen as complementary, not as overlapping in scope and functionality 🤝

This also means that applications acting as intermediaries, like search engines or archives that make resources discoverable, should treat Sunset info differently from caching info. These apps may use Sunset info to signal to users that a resource may become unavailable. But they still have to account for the fact that resource state can change in the meantime, and that Sunset info is a hint. So future resource availability may differ from the advertised timestamp 🦋

Part 1 is done, and we've got the good stuff in the back half 🧚💖

5. Sunset Scope ✨

okay so the Sunset header field is about the resource that sends it 💖. It's basically saying "hey, this specific resource is getting sunsetted soon" 🌸. BUT (big but) like we mentioned in Section 1.4, the scope of the Sunset info can sometimes be bigger than just the one resource it shows up on 👀.

Resources are allowed to define that bigger scope 🎀, and usually they'll document it so consumers know about it and can act accordingly 💅. Still, that bigger scope is invisible to consumers who don't know about the extra scoping rules 🙈. Those consumers won't realise the scope got bigger, so they'll read the Sunset info with its normal meaning (it only applies to the resource itself) ✨.

Using a bigger scope can still make sense, ngl 🦋, because Sunset info is only a hint anyway. It's optional information that can't be depended on, so clients should always be built so they can function without any Sunset info 🫶. A bigger scope can help clients pick up extra hints from resources. For example, a client might conclude that an API is being deprecated because its home/start resource announces a Sunset 👑. That could let clients make educated guesses about resources becoming unavailable 🧚.

The Sunset HTTP header field tells you about the upcoming retirement of a resource or a service 💜. A resource might also want to share info about how retirement will be handled for its resources or services 📚. That info can be broadly described by these three topics:

  • Sunset policy: The policy for which resources sunsets happen to, and in which way, may be published as part of the service's description 📋. Sunsets may only (or mostly) affect a subset of a service's resources, and they may be exposed according to a certain policy (e.g., one week in advance) ⏰.
  • Upcoming sunset: There may be extra info about an upcoming sunset, and that can be published as a resource that people looking for it can consume 🔍.
  • Sunset mitigation: There may be info about possible mitigation or migration strategies, like ways resource users can switch over to alternative resources or services 🔁.

Any info about the above (and possibly other stuff) can live at a URI, and you can link to that URI using the sunset link relation type 🔗. This spec doesn't put any constraints on the scope or type of the linked resource 🤷‍♀️. The scope can be for a resource or for a service. The type depends on the media type of the linked resource, and it can be aimed at humans, machines, or both 🤖.

If the linked resource does give machine-readable info, consumers should be careful before acting on it 😭. That info could, for example, tell consumers to use a migration rule so sunset resources can be accessed at new URIs. Honestly that's a potentially huge identity migration of resources, so it's crucial that the migration info is authentic and accurate 🚨.

7. IANA Considerations 🧾

7.1. The Sunset Response Header Field 🎀

The Sunset response header field has been added to the "Permanent Message Header Field Names" registry (see [RFC3864]), taking into account the guidelines given by HTTP/1.1 [RFC7231].

   Header Field Name: Sunset

   Protocol: http

   Status: informational

   Author/Change controller: IETF

   Reference: RFC 8594

The sunset link relation type has been added to the permanent "Link Relation Types" registry according to Section 4.2 of [RFC8288].

   Relation Name: sunset

   Description: Identifies a resource that provides information about
   the context's retirement policy.

   Reference: RFC 8594

8. Security Considerations 🔐

Okay, this section is important, bestie 😭. In general, info about upcoming sunsets can leak info that otherwise wouldn't be available 🕵️‍♀️. For example, a resource representing a registration can leak its expiration date when it exposes sunset info 💀. For that reason, any use of sunset info where the sunset is an expiration, or lets you calculate another date (like working out a creation date because you know resources expire after one year), should be treated the same way as if that info were made available directly in the resource's representation 🫣.

The Sunset header field SHOULD be treated as a resource hint 🧠. That means the resource is indicating its potential retirement, not guaranteeing it with certainty ✨. The only definitive test of whether the resource is actually available is to try interacting with it 🔬. Applications should never treat an advertised Sunset date as a definitive prediction of what's going to happen at that point in time 🚫. The Sunset indication might have been inserted by an intermediary, or the advertised date might get changed or withdrawn by the resource owner 🙃.

The main purpose of the Sunset header field is to signal intent, so applications using resources can get a warning ahead of time and react accordingly 🚦. What counts as an appropriate reaction (like switching to a different resource or service), what it's based on (like machine-readable formats that let the switch happen automatically), and when it happens (like ahead of the advertised date, or only once the resource actually becomes unavailable) is outside the scope of this spec 🙅‍♀️.

If a sunset policy is linked using the sunset link relation type, clients SHOULD be careful about taking any actions based on that info 😬. It SHOULD be verified that the info is authentic and accurate 🔍. Furthermore, it SHOULD be tested that this info is only applied to resources within the scope of the policy 🛡️. This keeps sunset policies from "hijacking" resources, for example by providing migration info for them 👿.

9. Example 📦

Say a resource was created in an archive that, for management or compliance reasons, keeps resources for ten years and then permanently deletes them 🗄️. The Sunset header field can be used to expose that info. If such a resource was created on November 11, 2016, then the following header field can be included in responses:

Sunset: Wed, 11 Nov 2026 11:11:11 GMT

This lets clients that understand the Sunset header field know the resource will likely become unavailable at that point in time ⏳. Clients can choose to ignore the info, adjust their own behaviour accordingly, or alert applications or users about the timestamp 🔔.

Even though the resource itself makes the Sunset header field available, there's no guarantee the resource will actually become unavailable 😅. And if it does, there's no guarantee about how the response will look for requests made after that timestamp 🤷‍♀️. In the archive example, the resource really may be permanently deleted, and requests for the URI after the Sunset timestamp may get a 410 Gone HTTP response 🪦. (This assumes the archive keeps track of the URIs it previously assigned. If it doesn't, the response may be a more generic 404 Not Found 🙈.)

Before the Sunset header field even shows up for the first time (it might not appear from the very beginning), the resource (or possibly just the "home" resource of the service context) may communicate its sunset policy using the sunset link relation type 📜. If that's communicated as an HTTP header field, it might look like this:

Link: <http://example.net/sunset>;rel="sunset";type="text/html"

In this case, the linked resource provides sunset policy info about the service context 🗺️. It might be developer docs, for example, telling them that the lifetime of a certain class of resources is ten years after creation, and that Sunset header fields will be served as soon as the sunset date is less than some given period away ⏰. It may also tell developers whether the service will respond with 410 or 404 after the sunset time, as discussed above 💜.

10. References 📚

10.1. Normative References 💖

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119,
           DOI 10.17487/RFC2119, March 1997,
           <https://www.rfc-editor.org/info/rfc2119>.

[RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
           Procedures for Message Header Fields", BCP 90, RFC 3864,
           DOI 10.17487/RFC3864, September 2004,
           <https://www.rfc-editor.org/info/rfc3864>.

[RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
           Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
           DOI 10.17487/RFC7231, June 2014,
           <https://www.rfc-editor.org/info/rfc7231>.

[RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
           2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
           May 2017, <https://www.rfc-editor.org/info/rfc8174>.

[RFC8288]  Nottingham, M., "Web Linking", RFC 8288,
           DOI 10.17487/RFC8288, October 2017,
           <https://www.rfc-editor.org/info/rfc8288>.

10.2. Informative References 🦋

[RFC7234]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
           Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
           RFC 7234, DOI 10.17487/RFC7234, June 2014,
           <https://www.rfc-editor.org/info/rfc7234>.

Acknowledgements 🫶

Huge thanks to Ben Campbell, Alissa Cooper, Benjamin Kaduk, Mirja Kuhlewind, Adam Roach, Phil Sturgeon, and Asbjorn Ulsberg for their comments and suggestions 🌟.

Author's Address 🧚

Erik Wilde

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