idnits 2.17.1 draft-wilde-sunset-header-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 28, 2017) is 2556 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7234 (Obsoleted by RFC 9111) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft CA Technologies 4 Intended status: Standards Track April 28, 2017 5 Expires: October 30, 2017 7 The Sunset HTTP Header 8 draft-wilde-sunset-header-02 10 Abstract 12 This specification defines the Sunset HTTP response header field, 13 which indicates that a URI is likely to become unresponsive at a 14 specified point in the future. 16 Note to Readers 18 This draft should be discussed on the ART mailing list 19 (). 21 Online access to all versions and files is available on GitHub 22 (). 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on October 30, 2017. 41 Copyright Notice 43 Copyright (c) 2017 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Temporary Resources . . . . . . . . . . . . . . . . . . . 2 60 1.2. Migration . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.3. Retention . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.4. Deprecation . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 64 3. The Sunset HTTP Response Header . . . . . . . . . . . . . . . 3 65 4. Sunset and Caching . . . . . . . . . . . . . . . . . . . . . 4 66 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 4 67 5.1. The Sunset Response Header . . . . . . . . . . . . . . . 4 68 6. Security Considerations . . . . . . . . . . . . . . . . . . . 5 69 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 70 8. Open Issues . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 72 9.1. Normative References . . . . . . . . . . . . . . . . . . 6 73 9.2. Informative References . . . . . . . . . . . . . . . . . 6 74 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 76 1. Introduction 78 As a general rule, URIs should be stable and persistent, so that 79 applications can use them as stable and persistent identifiers for 80 resources. However, there are many scenarios where for a variety of 81 reasons, URIs have a limited lifetime. In some of these scenarios, 82 this limited lifetime is known in advance. In this case, it can be 83 useful for clients if resources make this information about their 84 limited lifetime known. This specification defines the Sunset HTTP 85 response header field, which indicates that a URI is likely to become 86 unresponsive at a specified point in the future. 88 Possible scenarios for known lifetimes of resources include, but are 89 not limited to the following scenarios. 91 1.1. Temporary Resources 93 Some resources may have a limited lifetime by definition. For 94 example, a pending order represented by a resource may already list 95 all the details of the order, but may only exist for a limited time 96 unless it is confirmed and only then becomes permanent. In such a 97 case, the service managing the pending order can make this limited 98 lifetime explicit, allowing clients to understand that the pending 99 order, unless confirmed, will disappear at some point in time. 101 1.2. Migration 103 If resources are changing identity because a service migrates them, 104 then this may be known in advance. While it may not yet be 105 appropriate to use HTTP redirect status codes (3xx), it may be 106 interesting for clients to learn about the service's plan to take 107 down the original resource. 109 1.3. Retention 111 There are many cases where regulation or legislation require that 112 resources are kept available for a certain amount of time. However, 113 in many cases there also is a requirement for those resources to be 114 permanently deleted after some period of time. Since the deletion of 115 the resource in this scenario is governed by well-defined rules, it 116 could be made explicit for clients interacting with the resource. 118 1.4. Deprecation 120 For Web APIs one standard scenario is that an API or specific subsets 121 of an API may get deprecated. If this is planned in advance, then 122 for the time before the actual deprecation is rolled out, the 123 resources that will be affected by the deprecation can make the date 124 of their deprecation known. This allows consumers of the API to be 125 notified of the upcoming deprecation. 127 2. Terminology 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in RFC 2119 [RFC2119]. 133 3. The Sunset HTTP Response Header 135 The Sunset HTTP response header field allows a server to communicate 136 the fact that a resource is expected to become unresponsive at a 137 specific point in time. It provides information for clients which 138 they can use to control their usage of the resource. 140 The Sunset header contains a single timestamp which advertises the 141 point in time when the resource is expected to become unresponsive. 142 The Sunset value is an HTTP-date timestamp, as defined in 143 Section 7.1.1.1 of [RFC7231]. 145 Sunset = HTTP-date 147 For example 149 Sunset: Sat, 31 Dec 2018 23:59:59 GMT 151 Clients SHOULD treat Sunset timestamps as hints: It is not guaranteed 152 that the resource will in fact be available until that time, and will 153 not be available after that time. However, since this information is 154 provided by the resource itself, it does have some credibility. 156 After the Sunset time has arrived, it is likely that interactions 157 with the resource will either result in client-side errors (HTTP 4xx 158 status codes), or redirect responses (HTTP 3xx status codes). The 159 Sunset header does not expose any information about which of those 160 two behaviors can be expected. 162 Clients not interpreting an existing Sunset header field can operate 163 as usual and simply may experience the resource becoming unavailable 164 without getting any notification about it beforehand. 166 4. Sunset and Caching 168 It should be noted that the Sunset HTTP response header field serves 169 a different purpose than HTTP caching [RFC7234]. HTTP caching is 170 concerned with making resource representations (i.e., represented 171 resource state) reusable, so that they can be more efficiently used. 172 This is achieved by using header fields that allow clients and 173 intermediaries to better understand when a resource representation 174 can be reused, or when resource state (and thus the representation) 175 may have changed. 177 The Sunset header field is not concerned with resource state at all. 178 It only signals that a resource is expected to become unavailable at 179 a specific point in time. There are no assumptions about if, when, 180 or how often a resource may change state in the meantime. 182 For these reasons, the Sunset header field and HTTP caching should be 183 seen as complementary, and not as overlapping in scope and 184 functionality. 186 5. IANA Considerations 188 5.1. The Sunset Response Header 190 The Sunset response header should be added to the permanent registry 191 of message header fields (see [RFC3864]), taking into account the 192 guidelines given by HTTP/1.1 [RFC7231]. 194 Header Field Name: Sunset 196 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 198 Status: Standard 200 Author/Change controller: IETF 202 Specification document(s): RFC XXXX 204 6. Security Considerations 206 ... 208 7. Example 210 Assuming that a resource has been created in an archive that for 211 management or compliance reason only stores resources for two years, 212 and permanently deletes them afterwards, then the Sunset header field 213 can be used to expose this information. If such a resource has been 214 created on November 11, 2014, then the following header field can be 215 included in responses: 217 Sunset: Fri, 11 Nov 2018 11:11:11 GMT 219 This allows clients that are aware of the Sunset header field to 220 understand that the resource likely will become unavailable at the 221 specified point in time. Clients can decide to ignore this 222 information, adjust their own behavior accordingly, or alert 223 applications or users about this timestamp. 225 Even though the Sunset header information is made available by the 226 resource itself, there is no guarantee that the resource indeed will 227 become unavailable, and if so, how the response will look like for 228 requests made after that timestamp. In case of the archive used as 229 an example here, the resource indeed may be permanently deleted, and 230 requests for the URI after the Sunset timestamp may receive a "410 231 Gone" HTTP response. (This is assuming that the archive keeps track 232 of the URIs that it had previously assigned; if not, the response may 233 be a more generic "404 Not Found".) 235 8. Open Issues 237 Note to RFC Editor: Please remove this section before publication. 239 o Human readable explanation: It would be possible to include human- 240 readable information about the reason for the URI's disappearance. 241 This could either be done inline (probably just a simple string), 242 and/or by reference to a URI that will dereference to human- 243 readable information. 245 o Machine-readable explanation: It would be possible to include 246 machine-readable information about the reason for the URI's 247 disappearance. This could either be done inline (maybe name/value 248 pairs), and/or by reference to a URI that will dereference to 249 machine-readable information. 251 o New URI: If the resource's new URI is known (for example when a 252 service is migrating in a way that invalidates existing URIs, but 253 has a plan of how these will map to new URIs), then that URI could 254 be advertised in advance (i.e., it is not yet a 3xx, but clients 255 might want to start working with the new URI anyway). 257 o Timestamp in the past: Should it be allowed to have timestamps in 258 the past? Maybe either disallow them, or specifically allow them 259 and explain what they mean, for example the fact that a resource 260 that now is redirecting can expose information about when it 261 changed from being the primary resource to being the redirection. 263 o Sunrise: If resources have planned outages (server maintenance, 264 for example), then they might not just have a sunset to advertise, 265 but also a sunrise. This would allow consumers to learn about how 266 long a resource might be unavailable. 268 9. References 270 9.1. Normative References 272 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 273 Requirement Levels", RFC 2119, March 1997. 275 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 276 Procedures for Message Header Fields", BCP 90, RFC 3864, 277 September 2004. 279 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 280 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 282 9.2. Informative References 284 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 285 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 286 2014. 288 Author's Address 290 Erik Wilde 291 CA Technologies 293 Email: erik.wilde@dret.net 294 URI: http://dret.net/netdret/