idnits 2.17.1 draft-wilde-sunset-header-06.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 (July 17, 2018) is 2111 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) -- Looks like a reference, but probably isn't: '1' on line 436 ** 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 (~~), 1 warning (==), 4 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 July 17, 2018 5 Expires: January 18, 2019 7 The Sunset HTTP Header 8 draft-wilde-sunset-header-06 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 Note to Readers 20 This draft should be discussed on the ART mailing list 21 (). 23 Online access to all versions and files is available on GitHub 24 (). 26 Status of This Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at https://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on January 18, 2019. 43 Copyright Notice 45 Copyright (c) 2018 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (https://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 61 1.1. Temporary Resources . . . . . . . . . . . . . . . . . . . 3 62 1.2. Migration . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.3. Retention . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.4. Deprecation . . . . . . . . . . . . . . . . . . . . . . . 3 65 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. The Sunset HTTP Response Header . . . . . . . . . . . . . . . 4 67 4. Sunset and Caching . . . . . . . . . . . . . . . . . . . . . 5 68 5. The Sunset Link Relation Type . . . . . . . . . . . . . . . . 5 69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 70 6.1. The Sunset Response Header . . . . . . . . . . . . . . . 6 71 6.2. The Sunset Link Relation Type . . . . . . . . . . . . . . 6 72 7. Sunset Scope . . . . . . . . . . . . . . . . . . . . . . . . 6 73 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 7 74 9. Security Considerations . . . . . . . . . . . . . . . . . . . 8 75 10. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 76 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 11.1. Normative References . . . . . . . . . . . . . . . . . . 9 78 11.2. Informative References . . . . . . . . . . . . . . . . . 9 79 11.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 10 80 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10 81 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 10 83 1. Introduction 85 As a general rule, URIs should be stable and persistent, so that 86 applications can use them as stable and persistent identifiers for 87 resources. However, there are many scenarios where for a variety of 88 reasons, URIs have a limited lifetime. In some of these scenarios, 89 this limited lifetime is known in advance. In this case, it can be 90 useful for clients if resources make this information about their 91 limited lifetime known. This specification defines the Sunset HTTP 92 response header field, which indicates that a URI is likely to become 93 unresponsive at a specified point in the future. 95 This specification also defines a link relation type "sunset" that 96 allows to provide information about a resource's or a service's 97 sunset policy, and/or upcoming sunsets, and/or possible mitigation 98 scenarios for resource/service users. This specification does not 99 place any constraints on the nature of the linked resource, which can 100 be targeted at humans, at machines, or a combination of both. 102 Possible scenarios for known lifetimes of resources include, but are 103 not limited to the following scenarios. 105 1.1. Temporary Resources 107 Some resources may have a limited lifetime by definition. For 108 example, a pending order represented by a resource may already list 109 all the details of the order, but may only exist for a limited time 110 unless it is confirmed and only then becomes permanent. In such a 111 case, the service managing the pending order can make this limited 112 lifetime explicit, allowing clients to understand that the pending 113 order, unless confirmed, will disappear at some point in time. 115 1.2. Migration 117 If resources are changing identity because a service migrates them, 118 then this may be known in advance. While it may not yet be 119 appropriate to use HTTP redirect status codes (3xx), it may be 120 interesting for clients to learn about the service's plan to take 121 down the original resource. 123 1.3. Retention 125 There are many cases where regulation or legislation require that 126 resources are kept available for a certain amount of time. However, 127 in many cases there also is a requirement for those resources to be 128 permanently deleted after some period of time. Since the deletion of 129 the resource in this scenario is governed by well-defined rules, it 130 could be made explicit for clients interacting with the resource. 132 1.4. Deprecation 134 For Web APIs one standard scenario is that an API or specific subsets 135 of an API may get deprecated. If this is planned in advance, then 136 for the time before the actual deprecation is rolled out, the 137 resources that will be affected by the deprecation can make the date 138 of their deprecation known. This allows consumers of the API to be 139 notified of the upcoming deprecation. 141 In this scenario, the announced sunset date typically affects the 142 whole API or parts of it (i.e., sets of resources), and not just a 143 single resource. In this case, it makes sense for the API to define 144 rules how an announced sunset on a specific resource (such as the 145 API's home/start resource) implies the sunsetting of the whole API or 146 parts of it (i.e., sets of resources), and not just the resource 147 returning the sunset header field. Section Section 7 discusses how 148 the scope of the Sunset header field may change because of how a 149 resource is using it. 151 2. Terminology 153 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 154 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 155 document are to be interpreted as described in RFC 2119 [RFC2119]. 157 3. The Sunset HTTP Response Header 159 The Sunset HTTP response header field allows a server to communicate 160 the fact that a resource is expected to become unresponsive at a 161 specific point in time. It provides information for clients which 162 they can use to control their usage of the resource. 164 The Sunset header contains a single timestamp which advertises the 165 point in time when the resource is expected to become unresponsive. 166 The Sunset value is an HTTP-date timestamp, as defined in 167 Section 7.1.1.1 of [RFC7231], and SHOULD be a timestamp in the 168 future. 170 Timestamps in the past SHOULD be considered to mean the present time, 171 meaning that the resource is expected to become unavailable at any 172 point in time. 174 Sunset = HTTP-date 176 For example 178 Sunset: Sat, 31 Dec 2018 23:59:59 GMT 180 Clients SHOULD treat Sunset timestamps as hints: It is not guaranteed 181 that the resource will in fact be available until that time, and will 182 not be available after that time. However, since this information is 183 provided by the resource itself, it does have some credibility. 185 After the Sunset time has arrived, it is likely that interactions 186 with the resource will result in client-side errors (HTTP 4xx status 187 codes), redirect responses (HTTP 3xx status codes), or the client 188 might not be able to interact with the resource at all. The Sunset 189 header does not expose any information about which of those behaviors 190 can be expected. 192 Clients not interpreting an existing Sunset header field can operate 193 as usual and simply may experience the resource becoming unavailable 194 without getting any notification about it beforehand. 196 4. Sunset and Caching 198 It should be noted that the Sunset HTTP response header field serves 199 a different purpose than HTTP caching [RFC7234]. HTTP caching is 200 concerned with making resource representations (i.e., represented 201 resource state) reusable, so that they can be more efficiently used. 202 This is achieved by using header fields that allow clients and 203 intermediaries to better understand when a resource representation 204 can be reused, or when resource state (and thus the representation) 205 may have changed. 207 The Sunset header field is not concerned with resource state at all. 208 It only signals that a resource is expected to become unavailable at 209 a specific point in time. There are no assumptions about if, when, 210 or how often a resource may change state in the meantime. 212 For these reasons, the Sunset header field and HTTP caching should be 213 seen as complementary, and not as overlapping in scope and 214 functionality. 216 5. The Sunset Link Relation Type 218 The Sunset HTTP header field indicates the upcoming retirement of a 219 resource or a service. In addition, resource may want to make 220 information available that provides additional information about how 221 retirement will be handled for resources or services. This 222 information can be broadly described by the following three topics: 224 Sunset policy: The policy for which resources and in which way 225 sunsets may occur may be published as part of service's 226 description. Sunsets may only/mostly affect a subset of a 227 service's resources, and may be exposed according to a certain 228 policy (e.g., one week in advance). 230 Upcoming sunset: There may be additional information about an 231 upcoming sunset, which can be published as a resource that can be 232 consumed by those looking for this additional information. 234 Sunset mitigation: There may be information about possible 235 mitigation/migration strategies, such as possible ways how 236 resource users can switch to alternative resources/services. 238 Any information regarding the above issues (and possibly additional 239 ones) can be made available through a URI that then can be linked to 240 using the sunset link relation type. This specification places no 241 constraints on the scope or the type of the linked resource. The 242 scope can be for a resource or for a service. The type is determined 243 by the media type of the linked resource, and can be targeted at 244 humans, at machines, or a combination of both. 246 6. IANA Considerations 248 6.1. The Sunset Response Header 250 The Sunset response header should be added to the permanent registry 251 of message header fields (see [RFC3864]), taking into account the 252 guidelines given by HTTP/1.1 [RFC7231]. 254 Header Field Name: Sunset 256 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 258 Status: Standard 260 Author/Change controller: IETF 262 Specification document(s): RFC XXXX 264 6.2. The Sunset Link Relation Type 266 The sunset link relation type should be added to the permanent 267 registry of link relation types according to Section 4.2 of RFC 8288 268 [RFC8288]: 270 Relation Name: sunset 272 Description: Linking to a resource providing information about a 273 resource's or service's retirement policy and/or information. 275 Reference: RFC XXXX 277 7. Sunset Scope 279 The Sunset header field applies to the resource that returns it, 280 meaning that it announces the upcoming sunset of that specific 281 resources. However, as discussed in Section Section 1.4, there may 282 be scenarios where the scope of the announced Sunset information it 283 larger than just the single resource where it appears. 285 Resources are free to define such an increased scope, and usually 286 this scope will be documented by the resource, so that consumers of 287 the resource know about the increased scope and can behave 288 accordingly. However, it is important to take into account that such 289 increased scoping is invisible for consumers who are unaware of the 290 increased scoping rules. This means that these consumers will not be 291 aware of the increased scope, and will not interpret Sunset 292 information different from its standard meaning (i.e., it applies to 293 the resource only). 295 Using such an increased scope still may make sense, as Sunset 296 information is only a hint anyway, and thus is optional information 297 that cannot be depended on, and clients should always be implemented 298 in ways that allow them to function without Sunset information. 299 Increased scope information may help clients to glean additional 300 hints from resources (e.g., concluding that an API is being 301 deprecated because its home/start resource announces a Sunset), and 302 thus might allow them to implement behavior that allows them to make 303 educated guesses about resources becoming unavailable. 305 8. Implementation Status 307 Note to RFC Editor: Please remove this section before publication. 309 This section records the status of known implementations of the 310 protocol defined by this specification at the time of posting of this 311 Internet-Draft, and is based on a proposal described in RFC 6982 312 [RFC6982]. The description of implementations in this section is 313 intended to assist the IETF in its decision processes in progressing 314 drafts to RFCs. Please note that the listing of any individual 315 implementation here does not imply endorsement by the IETF. 316 Furthermore, no effort has been spent to verify the information 317 presented here that was supplied by IETF contributors. This is not 318 intended as, and must not be construed to be, a catalog of available 319 implementations or their features. Readers are advised to note that 320 other implementations may exist. 322 According to RFC 6982, "this will allow reviewers and working groups 323 to assign due consideration to documents that have the benefit of 324 running code, which may serve as evidence of valuable experimentation 325 and feedback that have made the implemented protocols more mature. 326 It is up to the individual working groups to use this information as 327 they see fit". 329 Name: https://github.com/hskrasek/guzzle-sunset 331 Licensing: MIT 333 Organization: WeWork 335 Name: https://github.com/wework/faraday-sunset 336 Licensing: MIT 338 Description: A Ruby gem adding HTTP client middleware for Sunset 339 to Faraday 341 Organization: WeWork 343 Name: https://github.com/wework/rails-sunset 345 Licensing: MIT 347 Description: Create shortcuts for backend developers to use Sunset 348 (The Rails Way). 350 Organization: Tyk Technologies 352 Name: https://github.com/TykTechnologies/tyk 354 Licensing: Mozilla Public License Version 2.0 356 Description: Configurable HTTP header for API version expiry. 357 (GitHub issue [1]) 359 9. Security Considerations 361 The Sunset header field should be treated as a resource hint, meaning 362 that the resource is indicating its potential retirement. The 363 definitive test whether or not the resource in fact is available or 364 not will be to attempt to interact with it. Applications should 365 never treat an advertised Sunset date as a definitive prediction that 366 is going to happen at the specified point in time. The Sunset 367 indication may have been inserted by an intermediary, or the 368 advertised date may get changed or withdrawn by the resource owner. 370 The main purpose of the Sunset header field is to signal intent, so 371 that applications using resources may get a warning ahead of time and 372 can react accordingly. What an appropriate reaction is (such as 373 switching to a different resource or service), what it will be based 374 on (such as machine-readable formats that allow the switching to be 375 done automatically), and when it will happen (such as ahead of the 376 advertised date or only when the resource in fact becomes 377 unavailable) is outside the scope of this specification. 379 10. Example 381 Assuming that a resource has been created in an archive that for 382 management or compliance reasons only stores resources for two years, 383 and permanently deletes them afterwards, then the Sunset header field 384 can be used to expose this information. If such a resource has been 385 created on November 11, 2014, then the following header field can be 386 included in responses: 388 Sunset: Fri, 11 Nov 2018 11:11:11 GMT 390 This allows clients that are aware of the Sunset header field to 391 understand that the resource likely will become unavailable at the 392 specified point in time. Clients can decide to ignore this 393 information, adjust their own behavior accordingly, or alert 394 applications or users about this timestamp. 396 Even though the Sunset header information is made available by the 397 resource itself, there is no guarantee that the resource indeed will 398 become unavailable, and if so, how the response will look like for 399 requests made after that timestamp. In case of the archive used as 400 an example here, the resource indeed may be permanently deleted, and 401 requests for the URI after the Sunset timestamp may receive a "410 402 Gone" HTTP response. (This is assuming that the archive keeps track 403 of the URIs that it had previously assigned; if not, the response may 404 be a more generic "404 Not Found".) 406 11. References 408 11.1. Normative References 410 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 411 Requirement Levels", RFC 2119, March 1997. 413 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 414 Procedures for Message Header Fields", BCP 90, RFC 3864, 415 September 2004. 417 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 418 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 420 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 421 DOI 10.17487/RFC8288, October 2017, 422 . 424 11.2. Informative References 426 [RFC6982] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 427 Code: The Implementation Status Section", RFC 6982, July 428 2013. 430 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 431 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 432 2014. 434 11.3. URIs 436 [1] https://github.com/TykTechnologies/tyk/issues/1626 438 Appendix A. Acknowledgements 440 Thanks for comments and suggestions provided by Phil Sturgeon and 441 Asbjoern Ulsberg. 443 Author's Address 445 Erik Wilde 446 CA Technologies 448 Email: erik.wilde@dret.net 449 URI: http://dret.net/netdret/