diff options
Diffstat (limited to 'doc/rfc/rfc8594.txt')
| -rw-r--r-- | doc/rfc/rfc8594.txt | 619 |
1 files changed, 619 insertions, 0 deletions
diff --git a/doc/rfc/rfc8594.txt b/doc/rfc/rfc8594.txt new file mode 100644 index 0000000..13d636f --- /dev/null +++ b/doc/rfc/rfc8594.txt @@ -0,0 +1,619 @@ + + + + + + +Internet Engineering Task Force (IETF) E. Wilde +Request for Comments: 8594 May 2019 +Category: Informational +ISSN: 2070-1721 + + + The Sunset HTTP Header Field + +Abstract + + This specification defines the Sunset HTTP response header field, + which indicates that a URI is likely to become unresponsive at a + specified point in the future. It also defines a sunset link + relation type that allows linking to resources providing information + about an upcoming resource or service sunset. + +Status of This Memo + + This document is not an Internet Standards Track specification; it is + 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. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc8594. + +Copyright Notice + + 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) in effect on the date of + publication of this document. Please review these documents + carefully, as 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 are provided without warranty as + described in the Simplified BSD License. + + + + + +Wilde Informational [Page 1] + +RFC 8594 Sunset Header May 2019 + + +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 + + As a general rule, URIs should be stable and persistent so that + applications can use them as stable and persistent identifiers for + resources. However, there are many scenarios where, for a variety of + reasons, URIs have a limited lifetime. In some of these scenarios, + this limited lifetime is known in advance. In this case, it can be + useful for clients if resources make this information about their + limited lifetime known. This specification defines the Sunset HTTP + response header field, which indicates that a URI is likely to become + unresponsive at a specified point in the future. + + This specification also defines a sunset link relation type that + allows information to be provided about 1) the sunset policy of a + resource or a service, and/or 2) upcoming sunsets, and/or 3) possible + mitigation scenarios for resource/service users. This specification + does not place any constraints on the nature of the linked resource, + which can be targeted to humans, machines, or both. + + Possible scenarios for known lifetimes of resources include, but are + not limited to, the following scenarios. + + + + + + + +Wilde Informational [Page 2] + +RFC 8594 Sunset Header May 2019 + + +1.1. Temporary Resources + + Some resources may have a limited lifetime by definition. For + example, a pending shopping order represented by a resource may + already list all order details, but it may only exist for a limited + time unless it is confirmed and only then becomes an acknowledged + shopping order. In such a case, the service managing the pending + shopping order can make this limited lifetime explicit, allowing + clients to understand that the pending order, unless confirmed, will + disappear at some point in time. + +1.2. Migration + + If resources are changing identity because a service migrates them, + then this may be known in advance. While it may not yet be + appropriate to use HTTP redirect status codes (3xx), it may be + interesting for clients to learn about the service's plan to take + down the original resource. + +1.3. Retention + + There are many cases where regulation or legislation require that + resources are kept available for a certain amount of time. However, + in many cases there is also a requirement for those resources to be + permanently deleted after some period of time. Since the deletion of + the resource 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 may get deprecated. Deprecation often happens in two + stages: the first stage being that the API is not the preferred or + recommended version anymore and the second stage being that the API + or a specific version of the API gets decommissioned. + + For the first stage (the API is not the preferred or recommended + version anymore), the Sunset header field is not appropriate: at this + stage, the API remains operational and can still be used. Other + mechanisms can be used for signaling that first stage that might help + with more visible deprecation management, but the Sunset header field + does not aim to represent that information. + + For the second stage (the API or a specific version of the API gets + decommissioned), the Sunset header field is appropriate: that is when + the API or a version does become unresponsive. From the Sunset + header field's point of view, it does not matter that the API may not + + + + +Wilde Informational [Page 3] + +RFC 8594 Sunset Header May 2019 + + + have been the preferred or recommended version anymore. 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 (i.e., just deprecated sets of + resources), and not just a single resource. In this case, it makes + sense for the API to define rules about how an announced sunset on a + specific resource (such as the API's home/start resource) implies the + sunsetting of the whole API or parts of it (i.e., sets of resources), + and not just the resource returning the sunset header field. + Section 5 discusses how the scope of the Sunset header field may + change because of 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. + +3. The Sunset HTTP Response Header Field + + The Sunset HTTP response header field allows a server to communicate + the fact that a resource is expected to become unresponsive at a + specific point in time. It provides information for clients that + they can use to control their usage of 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 SHOULD be a timestamp in the + future. + + It is safest to consider timestamps in the past mean the present + time, meaning that the resource is expected to become unavailable at + any time. + + Sunset = HTTP-date + + For example: + + Sunset: Sat, 31 Dec 2018 23:59:59 GMT + + + + + + + +Wilde Informational [Page 4] + +RFC 8594 Sunset Header May 2019 + + + Clients SHOULD treat Sunset timestamps as hints: it is not guaranteed + that the resource will, in fact, be available until that time and + will not be available after that time. However, since this + information is provided by the resource itself, it does have some + credibility. + + After the Sunset time has arrived, it is likely that interactions + with the resource will 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 does not expose any information about which of those + behaviors can be expected. + + Clients not interpreting an existing Sunset header field can operate + as usual and simply may experience the resource becoming unavailable + without recognizing any notification about it beforehand. + +4. Sunset and Caching + + It should be noted that the Sunset HTTP response header field serves + a different purpose than HTTP caching [RFC7234]. HTTP caching is + concerned with making resource representations (i.e., represented + resource state) reusable so that they can be used more efficiently. + This is achieved by using header fields that allow clients and + intermediaries to better understand when a resource representation + can be reused or when resource state (and, thus, the representation) + may have changed. + + The Sunset header field is not 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. + + For these reasons, the Sunset header field and HTTP caching should be + seen as complementary and not as overlapping in scope and + functionality. + + This also means that applications acting as intermediaries, such as + search engines or archives that make resources discoverable, should + treat Sunset information differently from caching information. These + applications may use Sunset information for signaling 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 information is a hint and, thus, future resource availability + may differ from the advertised timestamp. + + + + + + +Wilde Informational [Page 5] + +RFC 8594 Sunset Header May 2019 + + +5. Sunset Scope + + The Sunset header field applies to the resource that returns it, + meaning that it announces the upcoming sunset of that specific + resource. However, as discussed in Section 1.4, there may be + scenarios where the scope of the announced Sunset information is + larger than just the single resource where it appears. + + Resources are free to define such an increased scope, and usually + this scope will be documented by the resource so that consumers of + the resource know about the increased scope and can behave + accordingly. However, it is important to take into account that such + increased scoping is invisible for consumers who are unaware of the + increased scoping rules. This means that these consumers will not be + aware of the increased scope, and they will not interpret Sunset + information different from its standard meaning (i.e., it applies to + the resource only). + + Using such an increased scope still may make sense, as Sunset + information is only a hint anyway; thus, it is optional information + that cannot be depended on, and clients should always be implemented + in ways that allow them to function without Sunset information. + Increased scope information may help clients to glean additional + hints from resources (e.g., concluding that an API is being + deprecated because its home/start resource announces a Sunset) and, + thus, might allow them to implement behavior that allows them to make + educated guesses about resources becoming unavailable. + +6. The Sunset Link Relation Type + + The Sunset HTTP header field indicates the upcoming retirement of a + resource or a service. In addition, a resource may want to make + information available that provides additional information about how + retirement will be handled for resources or services. This + information can be broadly described by the following three topics: + + Sunset policy: The policy for which resources and in which way + sunsets may occur may be published as part of service's + description. Sunsets may only/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 additional information about an + upcoming sunset, which can be published as a resource that can + be consumed by those looking for this additional information. + + + + + + +Wilde Informational [Page 6] + +RFC 8594 Sunset Header May 2019 + + + Sunset mitigation: There may be information about possible + mitigation/migration strategies, such as possible ways how + resource users can switch to alternative resources/services. + + Any information regarding the above issues (and possibly additional + ones) can be made available through a URI that then can be linked to + using the sunset link relation type. This specification places no + constraints on the scope or the type of the linked resource. The + scope can be for a resource or for a service. The type is determined + by the media type of the linked resource and can be targeted to + humans, machines, or both. + + If the linked resource does provide machine-readable information, + consumers should be careful before acting on this information. Such + information may, for example, instruct consumers to use a migration + rule so that sunset resources can be accessed at new URIs. However, + this kind of information amounts to a possibly large-scale identity + migration of resources, so it is crucial that the migration + information 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 + + + + + + + + + + + + + + +Wilde Informational [Page 7] + +RFC 8594 Sunset Header May 2019 + + +7.2. The Sunset Link Relation Type + + 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 + + Generally speaking, information about upcoming sunsets can leak + information that otherwise might not be available. For example, a + resource representing a registration can leak information about the + expiration date when it exposes sunset information. For this reason, + any use of sunset information where the sunset represents an + expiration or allows the calculation of another date (such as + calculating a creation date because it is known that resources expire + after one year) should be treated in the same way as if this + information would be made available directly in the resource's + representation. + + The Sunset header field SHOULD be treated as a resource hint, meaning + that the resource is indicating (and not guaranteeing with certainty) + its potential retirement. The definitive test whether or not the + resource in fact is available will be to attempt to interact with it. + Applications should never treat an advertised Sunset date as a + definitive prediction of what is going to happen at the specified + point in time: the Sunset indication may have been inserted by an + intermediary or the advertised date may get changed or withdrawn by + the resource owner. + + The main purpose of the Sunset header field is to signal intent so + that applications using resources may get a warning ahead of time and + can react accordingly. What an appropriate reaction is (such as + switching to a different resource or service), what it will be based + on (such as machine-readable formats that allow the switching to be + done automatically), and when it will happen (such as ahead of the + advertised date or only when the resource in fact becomes + unavailable) is outside the scope of this specification. + + In cases where a sunset policy is linked by using the sunset link + relation type, clients SHOULD be careful about taking any actions + based on this information. It SHOULD be verified that the + information is authentic and accurate. Furthermore, it SHOULD be + + + +Wilde Informational [Page 8] + +RFC 8594 Sunset Header May 2019 + + + tested that this information is only applied to resources that are + within the scope of the policy, making sure that sunset policies + cannot "hijack" resources by for example providing migration + information for them. + +9. Example + + If a resource has been created in an archive that, for management or + compliance reasons, stores resources for ten years and permanently + deletes them afterwards, the Sunset header field can be used to + expose this information. If such a resource has been 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 allows clients that are aware of the Sunset header field to + understand that the resource likely will become unavailable at the + specified point in time. Clients can decide to ignore this + information, adjust their own behavior accordingly, or alert + applications or users about this timestamp. + + Even though the Sunset header field is made available by the resource + itself, there is no guarantee that the resource indeed will become + unavailable, and if so, how the response will look like for requests + made after that timestamp. In case of the archive used as an example + here, the resource indeed may be permanently deleted, and requests + for the URI after the Sunset timestamp may receive a "410 Gone" HTTP + response. (This is assuming that the archive keeps track of the URIs + that it had previously assigned; if not, the response may be a more + generic "404 Not Found".) + + Before the Sunset header field even appears for the first time (it + may not appear from the very beginning), it is possible that the + resource (or possibly just the "home" resource of the service + context) communicates its sunset policy by using the sunset link + relation type. If communicated as an HTTP header field, it might + look as follows: + + Link: <http://example.net/sunset>;rel="sunset";type="text/html" + + In this case, the linked resource provides sunset policy information + about the service context. It may be documentation aimed at + developers, for example, informing 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 + + + + + +Wilde Informational [Page 9] + +RFC 8594 Sunset Header May 2019 + + + less than some given period of time. It may also inform 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 + + Thanks for comments and suggestions provided by Ben Campbell, Alissa + Cooper, Benjamin Kaduk, Mirja Kuhlewind, Adam Roach, Phil Sturgeon, + and Asbjorn Ulsberg. + + + + + + + + +Wilde Informational [Page 10] + +RFC 8594 Sunset Header May 2019 + + +Author's Address + + Erik Wilde + + Email: erik.wilde@dret.net + URI: http://dret.net/netdret/ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Wilde Informational [Page 11] + |