idnits 2.17.1 draft-wilde-sunset-header-08.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 (November 29, 2018) is 1946 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC6982' is defined on line 405, but no explicit reference was found in the text ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 6982 (Obsoleted by RFC 7942) -- Obsolete informational reference (is this intentional?): RFC 7234 (Obsoleted by RFC 9111) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Wilde 3 Internet-Draft November 29, 2018 4 Intended status: Informational 5 Expires: June 2, 2019 7 The Sunset HTTP Header 8 draft-wilde-sunset-header-08 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. It also defines a sunset link 15 relation type that allows linking to resources providing information 16 about an upcoming resource or service sunset. 18 Status of This Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at https://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on June 2, 2019. 35 Copyright Notice 37 Copyright (c) 2018 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (https://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Temporary Resources . . . . . . . . . . . . . . . . . . . 3 54 1.2. Migration . . . . . . . . . . . . . . . . . . . . . . . . 3 55 1.3. Retention . . . . . . . . . . . . . . . . . . . . . . . . 3 56 1.4. Deprecation . . . . . . . . . . . . . . . . . . . . . . . 3 57 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. The Sunset HTTP Response Header . . . . . . . . . . . . . . . 4 59 4. Sunset and Caching . . . . . . . . . . . . . . . . . . . . . 5 60 5. Sunset Scope . . . . . . . . . . . . . . . . . . . . . . . . 5 61 6. The Sunset Link Relation Type . . . . . . . . . . . . . . . . 6 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 63 7.1. The Sunset Response Header . . . . . . . . . . . . . . . 6 64 7.2. The Sunset Link Relation Type . . . . . . . . . . . . . . 7 65 8. Security Considerations . . . . . . . . . . . . . . . . . . . 7 66 9. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 10.1. Normative References . . . . . . . . . . . . . . . . . . 9 69 10.2. Informative References . . . . . . . . . . . . . . . . . 9 70 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 9 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 73 1. Introduction 75 As a general rule, URIs should be stable and persistent, so that 76 applications can use them as stable and persistent identifiers for 77 resources. However, there are many scenarios where for a variety of 78 reasons, URIs have a limited lifetime. In some of these scenarios, 79 this limited lifetime is known in advance. In this case, it can be 80 useful for clients if resources make this information about their 81 limited lifetime known. This specification defines the Sunset HTTP 82 response header field, which indicates that a URI is likely to become 83 unresponsive at a specified point in the future. 85 This specification also defines a link relation type "sunset" that 86 allows to provide information about a resource's or a service's 87 sunset policy, and/or upcoming sunsets, and/or possible mitigation 88 scenarios for resource/service users. This specification does not 89 place any constraints on the nature of the linked resource, which can 90 be targeted at humans, at machines, or a combination of both. 92 Possible scenarios for known lifetimes of resources include, but are 93 not limited to the following scenarios. 95 1.1. Temporary Resources 97 Some resources may have a limited lifetime by definition. For 98 example, a pending order represented by a resource may already list 99 all the details of the order, but may only exist for a limited time 100 unless it is confirmed and only then becomes permanent. In such a 101 case, the service managing the pending order can make this limited 102 lifetime explicit, allowing clients to understand that the pending 103 order, unless confirmed, will disappear at some point in time. 105 1.2. Migration 107 If resources are changing identity because a service migrates them, 108 then this may be known in advance. While it may not yet be 109 appropriate to use HTTP redirect status codes (3xx), it may be 110 interesting for clients to learn about the service's plan to take 111 down the original resource. 113 1.3. Retention 115 There are many cases where regulation or legislation require that 116 resources are kept available for a certain amount of time. However, 117 in many cases there also is a requirement for those resources to be 118 permanently deleted after some period of time. Since the deletion of 119 the resource in this scenario is governed by well-defined rules, it 120 could be made explicit for clients interacting with the resource. 122 1.4. Deprecation 124 For Web APIs one standard scenario is that an API or specific subsets 125 of an API may get deprecated. If this is planned in advance, then 126 for the time before the actual deprecation is rolled out, the 127 resources that will be affected by the deprecation can make the date 128 of their deprecation known. This allows consumers of the API to be 129 notified of the upcoming deprecation. 131 In this scenario, the announced sunset date typically affects the 132 whole API or parts of it (i.e., sets of resources), and not just a 133 single resource. In this case, it makes sense for the API to define 134 rules how an announced sunset on a specific resource (such as the 135 API's home/start resource) implies the sunsetting of the whole API or 136 parts of it (i.e., sets of resources), and not just the resource 137 returning the sunset header field. Section Section 5 discusses how 138 the scope of the Sunset header field may change because of how a 139 resource is using it. 141 2. Terminology 143 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 144 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 145 document are to be interpreted as described in RFC 2119 [RFC2119]. 147 3. The Sunset HTTP Response Header 149 The Sunset HTTP response header field allows a server to communicate 150 the fact that a resource is expected to become unresponsive at a 151 specific point in time. It provides information for clients which 152 they can use to control their usage of the resource. 154 The Sunset header contains a single timestamp which advertises the 155 point in time when the resource is expected to become unresponsive. 156 The Sunset value is an HTTP-date timestamp, as defined in 157 Section 7.1.1.1 of [RFC7231], and SHOULD be a timestamp in the 158 future. 160 Timestamps in the past SHOULD be considered to mean the present time, 161 meaning that the resource is expected to become unavailable at any 162 time. 164 Sunset = HTTP-date 166 For example 168 Sunset: Sat, 31 Dec 2018 23:59:59 GMT 170 Clients SHOULD treat Sunset timestamps as hints: It is not guaranteed 171 that the resource will in fact be available until that time, and will 172 not be available after that time. However, since this information is 173 provided by the resource itself, it does have some credibility. 175 After the Sunset time has arrived, it is likely that interactions 176 with the resource will result in client-side errors (HTTP 4xx status 177 codes), redirect responses (HTTP 3xx status codes), or the client 178 might not be able to interact with the resource at all. The Sunset 179 header does not expose any information about which of those behaviors 180 can be expected. 182 Clients not interpreting an existing Sunset header field can operate 183 as usual and simply may experience the resource becoming unavailable 184 without getting any notification about it beforehand. 186 4. Sunset and Caching 188 It should be noted that the Sunset HTTP response header field serves 189 a different purpose than HTTP caching [RFC7234]. HTTP caching is 190 concerned with making resource representations (i.e., represented 191 resource state) reusable, so that they can be more efficiently used. 192 This is achieved by using header fields that allow clients and 193 intermediaries to better understand when a resource representation 194 can be reused, or when resource state (and thus the representation) 195 may have changed. 197 The Sunset header field is not concerned with resource state at all. 198 It only signals that a resource is expected to become unavailable at 199 a specific point in time. There are no assumptions about if, when, 200 or how often a resource may change state in the meantime. 202 For these reasons, the Sunset header field and HTTP caching should be 203 seen as complementary, and not as overlapping in scope and 204 functionality. 206 5. Sunset Scope 208 The Sunset header field applies to the resource that returns it, 209 meaning that it announces the upcoming sunset of that specific 210 resources. However, as discussed in Section Section 1.4, there may 211 be scenarios where the scope of the announced Sunset information it 212 larger than just the single resource where it appears. 214 Resources are free to define such an increased scope, and usually 215 this scope will be documented by the resource, so that consumers of 216 the resource know about the increased scope and can behave 217 accordingly. However, it is important to take into account that such 218 increased scoping is invisible for consumers who are unaware of the 219 increased scoping rules. This means that these consumers will not be 220 aware of the increased scope, and will not interpret Sunset 221 information different from its standard meaning (i.e., it applies to 222 the resource only). 224 Using such an increased scope still may make sense, as Sunset 225 information is only a hint anyway, and thus is optional information 226 that cannot be depended on, and clients should always be implemented 227 in ways that allow them to function without Sunset information. 228 Increased scope information may help clients to glean additional 229 hints from resources (e.g., concluding that an API is being 230 deprecated because its home/start resource announces a Sunset), and 231 thus might allow them to implement behavior that allows them to make 232 educated guesses about resources becoming unavailable. 234 6. The Sunset Link Relation Type 236 The Sunset HTTP header field indicates the upcoming retirement of a 237 resource or a service. In addition, resource may want to make 238 information available that provides additional information about how 239 retirement will be handled for resources or services. This 240 information can be broadly described by the following three topics: 242 Sunset policy: The policy for which resources and in which way 243 sunsets may occur may be published as part of service's 244 description. Sunsets may only/mostly affect a subset of a 245 service's resources, and may be exposed according to a certain 246 policy (e.g., one week in advance). 248 Upcoming sunset: There may be additional information about an 249 upcoming sunset, which can be published as a resource that can be 250 consumed by those looking for this additional information. 252 Sunset mitigation: There may be information about possible 253 mitigation/migration strategies, such as possible ways how 254 resource users can switch to alternative resources/services. 256 Any information regarding the above issues (and possibly additional 257 ones) can be made available through a URI that then can be linked to 258 using the sunset link relation type. This specification places no 259 constraints on the scope or the type of the linked resource. The 260 scope can be for a resource or for a service. The type is determined 261 by the media type of the linked resource, and can be targeted at 262 humans, at machines, or a combination of both. 264 If the linked resource does provide machine-readable information, 265 consumers should be careful before acting on this information. Such 266 information may, for example, instruct consumers to use a migration 267 rule so that sunset resources can be accessed at new URIs. However, 268 this kind of information amounts to a possibly large-scale identity 269 migration of resources, so it is crucial that the migration 270 information is authentic and accurate. 272 7. IANA Considerations 274 7.1. The Sunset Response Header 276 The Sunset response header should be added to the permanent registry 277 of message header fields (see [RFC3864]), taking into account the 278 guidelines given by HTTP/1.1 [RFC7231]. 280 Header Field Name: Sunset 281 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 283 Status: Informational 285 Author/Change controller: IETF 287 Specification document(s): RFC XXXX 289 7.2. The Sunset Link Relation Type 291 The sunset link relation type should be added to the permanent 292 registry of link relation types according to Section 4.2 of RFC 8288 293 [RFC8288]: 295 Relation Name: sunset 297 Description: Identifies a resource that provides information about 298 the context's retirement policy. 300 Reference: RFC XXXX 302 8. Security Considerations 304 Generally speaking, information about upcoming sunsets can leak 305 information that otherwise might not be available. For example, a 306 resource representing a registration can leak information about the 307 expiration date when it exposes sunset information. For this reason, 308 any use of sunset information where the sunset represents an 309 expiration or allows the calculation of another date (such as 310 calculating a creation date because it is known that resource expire 311 after one year) should be treated in the same way as if this 312 information would be made available directly in the resource's 313 representation. 315 The Sunset header field should be treated as a resource hint, meaning 316 that the resource is indicating its potential retirement. The 317 definitive test whether or not the resource in fact is available or 318 not will be to attempt to interact with it. Applications should 319 never treat an advertised Sunset date as a definitive prediction that 320 is going to happen at the specified point in time. The Sunset 321 indication may have been inserted by an intermediary, or the 322 advertised date may get changed or withdrawn by the resource owner. 324 The main purpose of the Sunset header field is to signal intent, so 325 that applications using resources may get a warning ahead of time and 326 can react accordingly. What an appropriate reaction is (such as 327 switching to a different resource or service), what it will be based 328 on (such as machine-readable formats that allow the switching to be 329 done automatically), and when it will happen (such as ahead of the 330 advertised date or only when the resource in fact becomes 331 unavailable) is outside the scope of this specification. 333 In cases where a sunset policy is linked by using the sunset link 334 relation type, clients should be careful about taking any actions 335 based on this information. It should be verified that the 336 information is authentic and accurate. Furthermore, it should be 337 tested that this information is only applied to resources that are 338 within the scope of the policy, making sure that sunset policies 339 cannot "hijack" resources by for example providing migration 340 information for them. 342 9. Example 344 Assuming that a resource has been created in an archive that for 345 management or compliance reasons stores resources for ten years, and 346 permanently deletes them afterwards, then the Sunset header field can 347 be used to expose this information. If such a resource has been 348 created on November 11, 2016, then the following header field can be 349 included in responses: 351 Sunset: Fri, 11 Nov 2026 11:11:11 GMT 353 This allows clients that are aware of the Sunset header field to 354 understand that the resource likely will become unavailable at the 355 specified point in time. Clients can decide to ignore this 356 information, adjust their own behavior accordingly, or alert 357 applications or users about this timestamp. 359 Even though the Sunset header information is made available by the 360 resource itself, there is no guarantee that the resource indeed will 361 become unavailable, and if so, how the response will look like for 362 requests made after that timestamp. In case of the archive used as 363 an example here, the resource indeed may be permanently deleted, and 364 requests for the URI after the Sunset timestamp may receive a "410 365 Gone" HTTP response. (This is assuming that the archive keeps track 366 of the URIs that it had previously assigned; if not, the response may 367 be a more generic "404 Not Found".) 369 Before the Sunset header even appears for the first time (it may not 370 appear fro the very beginning), it is possible that the resource (or 371 possibly just the "home" resource of the service context) 372 communicates its sunset policy by using the sunset link relation. If 373 communicated as an HTTP header field, it might look as following: 375 Link: ;rel="sunset";type="text/html" 376 In this case, the linked resource provides sunset policy information 377 about the service context. It may be documentation aimed at 378 developers, for example informing them that the lifetime of a certain 379 class of resources is ten years after creation, and that Sunset 380 headers will be served as soon as the sunset date is less than some 381 given period of time. It may also inform developers whether the 382 service will respond with 410 or 404 after the sunset time, as 383 discussed above. 385 10. References 387 10.1. Normative References 389 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 390 Requirement Levels", RFC 2119, March 1997. 392 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 393 Procedures for Message Header Fields", BCP 90, RFC 3864, 394 September 2004. 396 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 397 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 399 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 400 DOI 10.17487/RFC8288, October 2017, 401 . 403 10.2. Informative References 405 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 406 Code: The Implementation Status Section", RFC 6982, July 407 2013. 409 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 410 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 411 2014. 413 Appendix A. Acknowledgements 415 Thanks for comments and suggestions provided by Phil Sturgeon and 416 Asbjoern Ulsberg. 418 Author's Address 420 Erik Wilde 422 Email: erik.wilde@dret.net 423 URI: http://dret.net/netdret/