RFC 8594: The Sunset HTTP Header Field | RFC Editor
View as: Plain Text , Compact HTML RFC 8594 : The Sunset HTTP Header Field HTTP May 2019. E. Wilde Informational 25 subscribed Added to 6 Sets 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
The rest of this page is on the live site.