idnits 2.17.1 draft-wilde-sunset-header-11.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 (February 21, 2019) is 1891 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** 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 February 21, 2019 4 Intended status: Informational 5 Expires: August 25, 2019 7 The Sunset HTTP Header Field 8 draft-wilde-sunset-header-11 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 August 25, 2019. 35 Copyright Notice 37 Copyright (c) 2019 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 Field . . . . . . . . . . . . 4 59 4. Sunset and Caching . . . . . . . . . . . . . . . . . . . . . 5 60 5. Sunset Scope . . . . . . . . . . . . . . . . . . . . . . . . 5 61 6. The Sunset Link Relation Type . . . . . . . . . . . . . . . . 6 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 63 7.1. The Sunset Response Header Field . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . 10 70 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 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 shopping order represented by a resource may 99 already list all order details, but may only exist for a limited time 100 unless it is confirmed and only then becomes an acknowledged shopping 101 order. In such a case, the service managing the pending shopping 102 order can make this limited lifetime explicit, allowing clients to 103 understand that the pending order, unless confirmed, will disappear 104 at some point in time. 106 1.2. Migration 108 If resources are changing identity because a service migrates them, 109 then this may be known in advance. While it may not yet be 110 appropriate to use HTTP redirect status codes (3xx), it may be 111 interesting for clients to learn about the service's plan to take 112 down the original resource. 114 1.3. Retention 116 There are many cases where regulation or legislation require that 117 resources are kept available for a certain amount of time. However, 118 in many cases there also is a requirement for those resources to be 119 permanently deleted after some period of time. Since the deletion of 120 the resource in this scenario is governed by well-defined rules, it 121 could be made explicit for clients interacting with the resource. 123 1.4. Deprecation 125 For Web APIs one standard scenario is that an API or specific subsets 126 of an API may get deprecated. Deprecation often happens in two 127 stages, with the first stage being that the API is not the preferred 128 or recommended version anymore, and the second stage being that the 129 API or a specific version of the API gets decommissioned. 131 For the first stage (the API is not the preferred or recommended 132 version anymore), the Sunset header field is not appropriate, because 133 at this stage, the API remains operational and can still be used. 134 Other mechanisms can be used for signaling that first stage that 135 might help with more visible deprecation management, but the Sunset 136 header is not appropriate. 138 For the second stage (the API or a specific version of the API gets 139 decommissioned), the Sunset header field is appropriate, because that 140 is when the API or a version does become unresponsive. From the 141 Sunset header field's point of view, it does not matter that the API 142 may have been not the preferred or recommended version anymore. The 143 only thing that matters is that it will become unresponsive and that 144 this time can be advertised using the Sunset header field. 146 In this scenario, the announced sunset date typically affects all of 147 the deprecated API or parts of it (i.e., just deprecated sets of 148 resources), and not just a single resource. In this case, it makes 149 sense for the API to define rules how an announced sunset on a 150 specific resource (such as the API's home/start resource) implies the 151 sunsetting of the whole API or parts of it (i.e., sets of resources), 152 and not just the resource returning the sunset header field. 153 Section 5 discusses how the scope of the Sunset header field may 154 change because of how a resource is using it. 156 2. Terminology 158 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 159 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 160 "OPTIONAL" in this document are to be interpreted as described in BCP 161 14 [RFC2119] [RFC8174] when, and only when, they appear in all 162 capitals, as shown here. 164 3. The Sunset HTTP Response Header Field 166 The Sunset HTTP response header field allows a server to communicate 167 the fact that a resource is expected to become unresponsive at a 168 specific point in time. It provides information for clients which 169 they can use to control their usage of the resource. 171 The Sunset header field contains a single timestamp which advertises 172 the point in time when the resource is expected to become 173 unresponsive. The Sunset value is an HTTP-date timestamp, as defined 174 in Section 7.1.1.1 of [RFC7231], and SHOULD be a timestamp in the 175 future. 177 It is safest to consider timestamps in the past mean the present 178 time, meaning that the resource is expected to become unavailable at 179 any time. 181 Sunset = HTTP-date 183 For example 185 Sunset: Sat, 31 Dec 2018 23:59:59 GMT 187 Clients SHOULD treat Sunset timestamps as hints: It is not guaranteed 188 that the resource will in fact be available until that time, and will 189 not be available after that time. However, since this information is 190 provided by the resource itself, it does have some credibility. 192 After the Sunset time has arrived, it is likely that interactions 193 with the resource will result in client-side errors (HTTP 4xx status 194 codes), redirect responses (HTTP 3xx status codes), or the client 195 might not be able to interact with the resource at all. The Sunset 196 header field does not expose any information about which of those 197 behaviors can be expected. 199 Clients not interpreting an existing Sunset header field can operate 200 as usual and simply may experience the resource becoming unavailable 201 without recognizing any notification about it beforehand. 203 4. Sunset and Caching 205 It should be noted that the Sunset HTTP response header field serves 206 a different purpose than HTTP caching [RFC7234]. HTTP caching is 207 concerned with making resource representations (i.e., represented 208 resource state) reusable, so that they can be used more efficiently. 209 This is achieved by using header fields that allow clients and 210 intermediaries to better understand when a resource representation 211 can be reused, or when resource state (and thus the representation) 212 may have changed. 214 The Sunset header field is not concerned with resource state at all. 215 It only signals that a resource is expected to become unavailable at 216 a specific point in time. There are no assumptions about if, when, 217 or how often a resource may change state in the meantime. 219 For these reasons, the Sunset header field and HTTP caching should be 220 seen as complementary, and not as overlapping in scope and 221 functionality. 223 This also means that applications acting as intermediaries, such as 224 search engines or archives that make resources discoverable, should 225 treat Sunset information differently from caching information. These 226 applications may use Sunset information for signalling to users that 227 a resource may become unavailable. But they still have to account 228 for the fact that resource state can change in the meantime, and that 229 Sunset information is a hint and thus future resource availability 230 may differ from the advertised timestamp. 232 5. Sunset Scope 234 The Sunset header field applies to the resource that returns it, 235 meaning that it announces the upcoming sunset of that specific 236 resource. However, as discussed in Section Section 1.4, there may be 237 scenarios where the scope of the announced Sunset information it 238 larger than just the single resource where it appears. 240 Resources are free to define such an increased scope, and usually 241 this scope will be documented by the resource, so that consumers of 242 the resource know about the increased scope and can behave 243 accordingly. However, it is important to take into account that such 244 increased scoping is invisible for consumers who are unaware of the 245 increased scoping rules. This means that these consumers will not be 246 aware of the increased scope, and will not interpret Sunset 247 information different from its standard meaning (i.e., it applies to 248 the resource only). 250 Using such an increased scope still may make sense, as Sunset 251 information is only a hint anyway, and thus is optional information 252 that cannot be depended on, and clients should always be implemented 253 in ways that allow them to function without Sunset information. 254 Increased scope information may help clients to glean additional 255 hints from resources (e.g., concluding that an API is being 256 deprecated because its home/start resource announces a Sunset), and 257 thus might allow them to implement behavior that allows them to make 258 educated guesses about resources becoming unavailable. 260 6. The Sunset Link Relation Type 262 The Sunset HTTP header field indicates the upcoming retirement of a 263 resource or a service. In addition, resource may want to make 264 information available that provides additional information about how 265 retirement will be handled for resources or services. This 266 information can be broadly described by the following three topics: 268 Sunset policy: The policy for which resources and in which way 269 sunsets may occur may be published as part of service's 270 description. Sunsets may only/mostly affect a subset of a 271 service's resources, and may be exposed according to a certain 272 policy (e.g., one week in advance). 274 Upcoming sunset: There may be additional information about an 275 upcoming sunset, which can be published as a resource that can be 276 consumed by those looking for this additional information. 278 Sunset mitigation: There may be information about possible 279 mitigation/migration strategies, such as possible ways how 280 resource users can switch to alternative resources/services. 282 Any information regarding the above issues (and possibly additional 283 ones) can be made available through a URI that then can be linked to 284 using the sunset link relation type. This specification places no 285 constraints on the scope or the type of the linked resource. The 286 scope can be for a resource or for a service. The type is determined 287 by the media type of the linked resource, and can be targeted at 288 humans, at machines, or a combination of both. 290 If the linked resource does provide machine-readable information, 291 consumers should be careful before acting on this information. Such 292 information may, for example, instruct consumers to use a migration 293 rule so that sunset resources can be accessed at new URIs. However, 294 this kind of information amounts to a possibly large-scale identity 295 migration of resources, so it is crucial that the migration 296 information is authentic and accurate. 298 7. IANA Considerations 300 7.1. The Sunset Response Header Field 302 The Sunset response header field should be added to the permanent 303 registry of message header fields (see [RFC3864]), taking into 304 account the guidelines given by HTTP/1.1 [RFC7231]. 306 Header Field Name: Sunset 308 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 310 Status: Informational 312 Author/Change controller: IETF 314 Specification document(s): RFC XXXX 316 7.2. The Sunset Link Relation Type 318 The sunset link relation type should be added to the permanent 319 registry of link relation types according to Section 4.2 of RFC 8288 320 [RFC8288]: 322 Relation Name: sunset 324 Description: Identifies a resource that provides information about 325 the context's retirement policy. 327 Reference: RFC XXXX 329 8. Security Considerations 331 Generally speaking, information about upcoming sunsets can leak 332 information that otherwise might not be available. For example, a 333 resource representing a registration can leak information about the 334 expiration date when it exposes sunset information. For this reason, 335 any use of sunset information where the sunset represents an 336 expiration or allows the calculation of another date (such as 337 calculating a creation date because it is known that resources expire 338 after one year) should be treated in the same way as if this 339 information would be made available directly in the resource's 340 representation. 342 The Sunset header field SHOULD be treated as a resource hint, meaning 343 that the resource is indicating (and not guaranteeing with certainty) 344 its potential retirement. The definitive test whether or not the 345 resource in fact is available or not will be to attempt to interact 346 with it. Applications should never treat an advertised Sunset date 347 as a definitive prediction that is going to happen at the specified 348 point in time. The Sunset indication may have been inserted by an 349 intermediary, or the advertised date may get changed or withdrawn by 350 the resource owner. 352 The main purpose of the Sunset header field is to signal intent, so 353 that applications using resources may get a warning ahead of time and 354 can react accordingly. What an appropriate reaction is (such as 355 switching to a different resource or service), what it will be based 356 on (such as machine-readable formats that allow the switching to be 357 done automatically), and when it will happen (such as ahead of the 358 advertised date or only when the resource in fact becomes 359 unavailable) is outside the scope of this specification. 361 In cases where a sunset policy is linked by using the sunset link 362 relation type, clients SHOULD be careful about taking any actions 363 based on this information. It SHOULD be verified that the 364 information is authentic and accurate. Furthermore, it SHOULD be 365 tested that this information is only applied to resources that are 366 within the scope of the policy, making sure that sunset policies 367 cannot "hijack" resources by for example providing migration 368 information for them. 370 9. Example 372 Assuming that a resource has been created in an archive that for 373 management or compliance reasons stores resources for ten years, and 374 permanently deletes them afterwards, then the Sunset header field can 375 be used to expose this information. If such a resource has been 376 created on November 11, 2016, then the following header field can be 377 included in responses: 379 Sunset: Fri, 11 Nov 2026 11:11:11 GMT 381 This allows clients that are aware of the Sunset header field to 382 understand that the resource likely will become unavailable at the 383 specified point in time. Clients can decide to ignore this 384 information, adjust their own behavior accordingly, or alert 385 applications or users about this timestamp. 387 Even though the Sunset header field is made available by the resource 388 itself, there is no guarantee that the resource indeed will become 389 unavailable, and if so, how the response will look like for requests 390 made after that timestamp. In case of the archive used as an example 391 here, the resource indeed may be permanently deleted, and requests 392 for the URI after the Sunset timestamp may receive a "410 Gone" HTTP 393 response. (This is assuming that the archive keeps track of the URIs 394 that it had previously assigned; if not, the response may be a more 395 generic "404 Not Found".) 397 Before the Sunset header field even appears for the first time (it 398 may not appear from the very beginning), it is possible that the 399 resource (or possibly just the "home" resource of the service 400 context) communicates its sunset policy by using the sunset link 401 relation. If communicated as an HTTP header field, it might look as 402 following: 404 Link: ;rel="sunset";type="text/html" 406 In this case, the linked resource provides sunset policy information 407 about the service context. It may be documentation aimed at 408 developers, for example informing them that the lifetime of a certain 409 class of resources is ten years after creation, and that Sunset 410 header fields will be served as soon as the sunset date is less than 411 some given period of time. It may also inform developers whether the 412 service will respond with 410 or 404 after the sunset time, as 413 discussed above. 415 10. References 417 10.1. Normative References 419 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 420 Requirement Levels", RFC 2119, March 1997. 422 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 423 Procedures for Message Header Fields", BCP 90, RFC 3864, 424 September 2004. 426 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 427 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 429 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 430 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 431 May 2017, . 433 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 434 DOI 10.17487/RFC8288, October 2017, 435 . 437 10.2. Informative References 439 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 440 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 441 2014. 443 Appendix A. Acknowledgements 445 Thanks for comments and suggestions provided by Ben Campbell, Alissa 446 Cooper, Benjamin Kaduk, Mirja Kuhlewind, Adam Roach, Phil Sturgeon, 447 and Asbjorn Ulsberg. 449 Author's Address 451 Erik Wilde 453 Email: erik.wilde@dret.net 454 URI: http://dret.net/netdret/