idnits 2.17.1 draft-dalal-deprecation-header-01.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 : ---------------------------------------------------------------------------- ** There are 3 instances of too long lines in the document, the longest one being 61 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 17, 2019) is 1775 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 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Dalal 3 Internet-Draft 4 Intended status: Standards Track E. Wilde 5 Expires: December 19, 2019 June 17, 2019 7 The Deprecation HTTP Header Field 8 draft-dalal-deprecation-header-01 10 Abstract 12 The HTTP Deprecation response header field can be used to signal to 13 consumers of a URI-identified resource that the resource has been 14 deprecated. Additionally, the deprecation link relation can be used 15 to link to a resource that provides additional context for the 16 deprecation, and possibly ways in which clients can find a 17 replacement for the deprecated resource. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on December 19, 2019. 36 Copyright Notice 38 Copyright (c) 2019 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 55 2. The Deprecation HTTP Response Header Field . . . . . . . . . 3 56 2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3. The Deprecation Link Relation Type . . . . . . . . . . . . . 4 58 3.1. Documentation . . . . . . . . . . . . . . . . . . . . . . 4 59 4. Recommend Replacement . . . . . . . . . . . . . . . . . . . . 5 60 5. Sunset . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 6. Resource Behavior . . . . . . . . . . . . . . . . . . . . . . 6 62 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 63 7.1. The Deprecation Response Header Field . . . . . . . . . . 6 64 7.2. The Deprecation Link Relation Type . . . . . . . . . . . 7 65 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 7 66 9. Security Considerations . . . . . . . . . . . . . . . . . . . 8 67 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 69 11.1. Normative References . . . . . . . . . . . . . . . . . . 9 70 11.2. Informative References . . . . . . . . . . . . . . . . . 11 71 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 11 72 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 74 1. Introduction 76 Deprecation of a URI-identified resource is a technique to 77 communicate information about the lifecycle of a resource. It 78 encourages applications to migrate away from the resource, 79 discourages applications from forming new dependencies on the 80 resource, and informs applications about the risk of continuing 81 dependence upon the resource. 83 The act of deprecation does not change any behavior of the resource. 84 It just informs client of the fact that a resource is deprecated. 85 The Deprecation HTTP response header field MAY be used to convey this 86 fact at runtime to clients. The header field can carry information 87 indicating since when the deprecation is in effect. 89 In addition to the Deprecation header field the resource provider can 90 use other header fields to convey additional information related to 91 deprecation. For example, information such as where to find 92 documentation related to the deprecation or what should be used as an 93 alternate and when the deprecated resource would be unreachable, etc. 94 Alternates of a resource can be similar resource(s) or a newer 95 version of the same resource. 97 1.1. Notational Conventions 99 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 100 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 101 "OPTIONAL" in this document are to be interpreted as described in BCP 102 14 [RFC2119] [RFC8174] when, and only when, they appear in all 103 capitals, as shown here. 105 This specification uses the Augmented Backus-Naur Form (ABNF) 106 notation of [RFC5234] and includes, by reference, the HTTP-date rule 107 as defined within Sections 3.2.6 and 7 of [RFC7230] and Section 7.1.1 108 of [RFC7231]. 110 2. The Deprecation HTTP Response Header Field 112 The "Deprecation" HTTP response header field allows a server to 113 communicate to a client that the URI-identified resource in context 114 of the message is or will be deprecated. 116 2.1. Syntax 118 The "Deprecation" response header field describes the deprecation. 119 It either shows the deprecation date, which may be in the future (the 120 resource context will be deprecated at that date) or in the past (the 121 resource context has been deprecated at that date), or it simply 122 flags the resource context as being deprecated: 124 Deprecation = HTTP-date / "true" 126 Servers MUST NOT include more than one "Deprecation" header field in 127 the same response. 129 The date, if present, is the date when the resource context was or 130 will be deprecated. It is in the form of an HTTP-date timestamp, as 131 defined in Section 7.1.1.1 of [RFC7231]. 133 The following example shows that the resource context has been 134 deprecated on Friday, November 11, 2018 at 23:59:59 GMT: 136 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 138 The deprecation date can be in the future. If the value of "date" is 139 in the future, it means that the resource will be deprecated at the 140 given date in future. 142 If the deprecation date is not known, the header field can carry the 143 simple string "true", indicating that the resource context is 144 deprecated, without indicating when that happened: 146 Deprecation: true 148 3. The Deprecation Link Relation Type 150 In addition to the Deprecation HTTP header field, the server can use 151 links with the "deprecation" link relation type to communicate to the 152 client where to find more information about deprecation of the 153 context. This can happen before the actual deprecation, to make a 154 deprecation policy discoverable, or after deprecation, when there may 155 be documentation about the deprecation, and possibly documentation of 156 how to manage it. 158 This specification places no restrictions on the representation of 159 the interlinked deprecation policy. In particular, the deprecation 160 policy may be available as human-readable documentation or as 161 machine-readable description. 163 3.1. Documentation 165 For a URI-identified resource, deprecation could involve one or more 166 parts of request, response or both. These parts could be one or more 167 of the following. 169 o URI - deprecation of one ore more query parameter(s) or path 170 element(s) 172 o method - HTTP method for the resource is deprecated 174 o request header - one or more HTTP request header(s) is deprecated 176 o response header - HTTP response header(s) is deprecated 178 o request body - request body contains one or more deprecated 179 element(s) 181 o response body - response body contains one or more deprecated 182 element(s) 184 The purpose of the "Deprecation" header is to provide just enough 185 "hints" about the deprecation to the client application developer. 186 It is safe to assume that on reception of the "Deprecation" header, 187 the client developer would look up the resource's documentation in 188 order to find deprecation related semantics. The resource developer 189 could provide a link to the resource documentation using a "Link" 190 header with relation type "deprecation" as shown below. 192 Link: ; rel="deprecation"; type="text/html" 193 In this example, the interlinked content provides additional 194 information about the deprecation of the resource context. In this 195 example, there is no Deprecation header field in the response, and 196 thus the resource is not deprecated. However, the resource already 197 exposes a link where information is available how deprecation is 198 managed for the context. This may be documentation explaining the 199 use of the Deprecation header field, and also explaining under which 200 circumstances and with which policies (announcement before 201 deprecation; continued operation after deprecation) deprecation might 202 be happening. 204 The following example uses the same link header, but also announces a 205 deprecation date using a Deprecation header field. 207 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 208 Link: ; rel="deprecation"; type="text/html" 210 Given that the deprecation date is in the past, the linked resource 211 may have been updated to include information about the deprecation, 212 allowing clients to discover information about the deprecation that 213 happened. 215 4. Recommend Replacement 217 "Link" [RFC8288] header could be used in addition to the 218 "Deprecation" header to recommend the client application about 219 available alternates to the deprecated resource. Following relation 220 types as defined in [RFC8288] are RECOMMENDED to use for the purpose. 222 o "successor-version": Points to a resource containing the successor 223 version. [RFC5829] 225 o "latest-version": Points to a resource containing the latest 226 (e.g., current) version. [RFC5829] 228 o "alternate": Designates a substitute. [W3C.REC-html401-19991224] 230 The following example provides link to the successor version of the 231 requested resource that is deprecated. 233 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 234 Link: ; rel="successor-version" 236 This example provides link to an alternate resource to the requested 237 resource that is deprecated. 239 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 240 Link: ; rel="alternate" 242 5. Sunset 244 In addition to the deprecation related information, if the resource 245 provider wants to convey to the client application that the 246 deprecated resource is expected to become unresponsive at a specific 247 point in time, the [RFC8594] header could be used in addition to the 248 "Deprecation" header. 250 The following example shows that the resource in context has been 251 deprecated since Friday, November 11, 2018 at 23:59:59 GMT and its 252 sunset date is Friday, November 11, 2020 at 23:59:59 GMT. 254 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 255 Sunset: Wed, 11 Nov 2020 23:59:59 GMT 257 6. Resource Behavior 259 The act of deprecation does not change any behavior of the resource. 260 Deprecated resources SHOULD keep functioning as before, allowing 261 consumers to still use the resources in the same way as they did 262 before the resources were declared deprecated. 264 7. IANA Considerations 266 7.1. The Deprecation Response Header Field 268 The "Deprecation" response header should be added to the permanent 269 registry of message header fields (see [RFC3864]), taking into 270 account the guidelines given by HTTP/1.1 [RFC7231]. 272 Header Field Name: Deprecation 274 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 276 Status: Standard 278 Author: Sanjay Dalal , 279 Erik Wilde 281 Change controller: IETF 283 Specification document: this specification, 284 Section 2 "The Deprecation HTTP Response Header Field" 286 7.2. The Deprecation Link Relation Type 288 The "deprecation" link relation type should be added to the permanent 289 registry of link relation types according to Section 4.2 of 290 [RFC8288]: 292 Relation Type: deprecation 294 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 296 Status: Standard 298 Author: Sanjay Dalal , 299 Erik Wilde 301 Change controller: IETF 303 Specification document: this specification, 304 Section 3 "The Deprecation Link Relation Type" 306 8. Implementation Status 308 Note to RFC Editor: Please remove this section before publication. 310 This section records the status of known implementations of the 311 protocol defined by this specification at the time of posting of this 312 Internet-Draft, and is based on a proposal described in [RFC7942]. 313 The description of implementations in this section is intended to 314 assist the IETF in its decision processes in progressing drafts to 315 RFCs. Please note that the listing of any individual implementation 316 here does not imply endorsement by the IETF. Furthermore, no effort 317 has been spent to verify the information presented here that was 318 supplied by IETF contributors. This is not intended as, and must not 319 be construed to be, a catalog of available implementations or their 320 features. Readers are advised to note that other implementations may 321 exist. 323 According to RFC 7942, "this will allow reviewers and working groups 324 to assign due consideration to documents that have the benefit of 325 running code, which may serve as evidence of valuable experimentation 326 and feedback that have made the implemented protocols more mature. 327 It is up to the individual working groups to use this information as 328 they see fit". 330 Organization: Zapier 332 Description: Zapier uses two custom HTTP headers named "X-API- 333 Deprecation-Date" and "X-API-Deprecation-Info" 334 Reference: https://zapier.com/engineering/api-geriatrics/ 336 Organization: IBM 338 IBM uses a custom HTTP header named "Deprecated" 340 Reference: 341 https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/ 342 com.ibm.qradar.doc/c_rest_api_getting_started.html 344 Organization: Ultipro 346 Description: Ultipro uses the HTTP "Warning" header as described in 347 Section 5.5 of [RFC7234] with code "299" 349 Reference: https://connect.ultipro.com/api-deprecation 351 Organization: Clearbit 353 Description: Clearbit uses a custom HTTP header named "X-API-Warn" 355 Reference: https://blog.clearbit.com/dealing-with-deprecation/ 357 Organization: PayPal 359 Description: PayPal uses a custom HTTP header named "PayPal- 360 Deprecated" 362 Reference: https://github.com/paypal/api-standards/blob/master/api- 363 style-guide.md#runtime 365 9. Security Considerations 367 The Deprecation header field SHOULD be treated as a hint, meaning 368 that the resource is indicating (and not guaranteeing with certainty) 369 that it is deprecated. Applications consuming the resource SHOULD 370 check the resource documentation to verify authenticity and accuracy. 371 Resource documentation SHOULD provide additional information about 372 the deprecation including recommendation(s) for replacement. 374 In cases, where the Deprecation header field value is a date in 375 future, it can lead to information that otherwise might not be 376 available. Therefore, applications consuming the resource SHOULD 377 verify the resource documentation and if possible, consult the 378 resource developer to discuss potential impact due to deprecation and 379 plan for possible transition to recommended resource. 381 In cases where "Link" header is used to provide more documentation 382 and/or recommendation for replacement, one should assume that the 383 content of the "Link" header field may not be secure, private or 384 integrity-guaranteed, and due caution should be exercised when using 385 it. Applications consuming the resource SHOULD check the referred 386 resource documentation to verify authenticity and accuracy. 388 The suggested "Link" header fields make extensive use of IRIs and 389 URIs. See [RFC3987] for security considerations relating to IRIs. 390 See [RFC3986] for security considerations relating to URIs. See 391 [RFC7230] for security considerations relating to HTTP headers. 393 Applications that take advantage of typed links should consider the 394 attack vectors opened by automatically following, trusting, or 395 otherwise using links gathered from the HTTP headers. In particular, 396 Link headers that use the "successor-version", "latest-version" or 397 "alternate" relation types should be treated with due caution. See 398 [RFC5829] for security considerations relating to these link relation 399 types. 401 10. Examples 403 The first example shows a deprecation header field without date 404 information: 406 Deprecation: true 408 The second example shows a deprecation header with date information 409 and a link to the successor version: 411 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 412 Link: ; rel="successor-version" 414 The third example shows a deprecation header field with links for the 415 successor version and for the API's deprecation policy. In addition, 416 it shows the sunset date for the deprecated resource: 418 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 419 Sunset: Wed, 11 Nov 2020 23:59:59 GMT 420 Link: ; rel="successor-version", ; rel="deprecation" 422 11. References 424 11.1. Normative References 426 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 427 Requirement Levels", BCP 14, RFC 2119, 428 DOI 10.17487/RFC2119, March 1997, 429 . 431 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 432 Procedures for Message Header Fields", BCP 90, RFC 3864, 433 DOI 10.17487/RFC3864, September 2004, 434 . 436 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 437 Resource Identifier (URI): Generic Syntax", STD 66, 438 RFC 3986, DOI 10.17487/RFC3986, January 2005, 439 . 441 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 442 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 443 January 2005, . 445 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 446 Specifications: ABNF", STD 68, RFC 5234, 447 DOI 10.17487/RFC5234, January 2008, 448 . 450 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 451 Protocol (HTTP/1.1): Message Syntax and Routing", 452 RFC 7230, DOI 10.17487/RFC7230, June 2014, 453 . 455 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 456 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 457 DOI 10.17487/RFC7231, June 2014, 458 . 460 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 461 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 462 RFC 7234, DOI 10.17487/RFC7234, June 2014, 463 . 465 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 466 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 467 May 2017, . 469 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 470 DOI 10.17487/RFC8288, October 2017, 471 . 473 11.2. Informative References 475 [RFC5829] Brown, A., Clemm, G., and J. Reschke, Ed., "Link Relation 476 Types for Simple Version Navigation between Web 477 Resources", RFC 5829, DOI 10.17487/RFC5829, April 2010, 478 . 480 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 481 Code: The Implementation Status Section", BCP 205, 482 RFC 7942, DOI 10.17487/RFC7942, July 2016, 483 . 485 [RFC8594] Wilde, E., "The Sunset HTTP Header Field", RFC 8594, 486 DOI 10.17487/RFC8594, May 2019, 487 . 489 Appendix A. Acknowledgments 491 The authors would like to thank Mark Nottingham and Nikhil Kolekar 492 for reviewing this specification. 494 The authors take all responsibility for errors and omissions. 496 Authors' Addresses 498 Sanjay Dalal 500 Email: sanjay.dalal@cal.berkeley.edu 501 URI: https://github.com/sdatspun2 503 Erik Wilde 505 Email: erik.wilde@dret.net 506 URI: http://dret.net/netdret