idnits 2.17.1 draft-dalal-deprecation-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 : ---------------------------------------------------------------------------- ** 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 (December 17, 2019) is 1592 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: June 19, 2020 December 17, 2019 7 The Deprecation HTTP Header Field 8 draft-dalal-deprecation-header-02 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 June 19, 2020. 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 HTTP Response Header Field . . . . . . . 6 64 7.2. The Deprecation Link Relation Type . . . . . . . . . . . 7 65 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 7 66 8.1. Implementing the Deprecation Header Field . . . . . . . . 8 67 8.2. Implementing the Concept . . . . . . . . . . . . . . . . 8 68 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 69 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 11.1. Normative References . . . . . . . . . . . . . . . . . . 10 72 11.2. Informative References . . . . . . . . . . . . . . . . . 11 73 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 11 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 76 1. Introduction 78 Deprecation of a URI-identified resource is a technique to 79 communicate information about the lifecycle of a resource. It 80 encourages applications to migrate away from the resource, 81 discourages applications from forming new dependencies on the 82 resource, and informs applications about the risk of continuing 83 dependence upon the resource. 85 The act of deprecation does not change any behavior of the resource. 86 It just informs client of the fact that a resource is deprecated. 87 The Deprecation HTTP response header field MAY be used to convey this 88 fact at runtime to clients. The header field can carry information 89 indicating since when the deprecation is in effect. 91 In addition to the Deprecation header field the resource provider can 92 use other header fields to convey additional information related to 93 deprecation. For example, information such as where to find 94 documentation related to the deprecation or what should be used as an 95 alternate and when the deprecated resource would be unreachable, etc. 97 Alternates of a resource can be similar resource(s) or a newer 98 version of the same resource. 100 1.1. Notational Conventions 102 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 103 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 104 "OPTIONAL" in this document are to be interpreted as described in BCP 105 14 [RFC2119] [RFC8174] when, and only when, they appear in all 106 capitals, as shown here. 108 This specification uses the Augmented Backus-Naur Form (ABNF) 109 notation of [RFC5234] and includes, by reference, the IMF-fixdate 110 rule as defined in Section 7.1.1.1 of [RFC7231]. 112 2. The Deprecation HTTP Response Header Field 114 The "Deprecation" HTTP response header field allows a server to 115 communicate to a client that the URI-identified resource in context 116 of the message is or will be deprecated. 118 2.1. Syntax 120 The "Deprecation" response header field describes the deprecation. 121 It either shows the deprecation date, which may be in the future (the 122 resource context will be deprecated at that date) or in the past (the 123 resource context has been deprecated at that date), or it simply 124 flags the resource context as being deprecated: 126 Deprecation = IMF-fixdate / "true" 128 Servers MUST NOT include more than one "Deprecation" header field in 129 the same response. 131 The date, if present, is the date when the resource context was or 132 will be deprecated. It is in the form of an IMF-fixdate timestamp. 134 The following example shows that the resource context has been 135 deprecated on Friday, November 11, 2018 at 23:59:59 GMT: 137 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 139 The deprecation date can be in the future. If the value of "date" is 140 in the future, it means that the resource will be deprecated at the 141 given date in future. 143 If the deprecation date is not known, the header field can carry the 144 simple string "true", indicating that the resource context is 145 deprecated, without indicating when that happened: 147 Deprecation: true 149 3. The Deprecation Link Relation Type 151 In addition to the Deprecation HTTP header field, the server can use 152 links with the "deprecation" link relation type to communicate to the 153 client where to find more information about deprecation of the 154 context. This can happen before the actual deprecation, to make a 155 deprecation policy discoverable, or after deprecation, when there may 156 be documentation about the deprecation, and possibly documentation of 157 how to manage it. 159 This specification places no restrictions on the representation of 160 the interlinked deprecation policy. In particular, the deprecation 161 policy may be available as human-readable documentation or as 162 machine-readable description. 164 3.1. Documentation 166 For a URI-identified resource, deprecation could involve one or more 167 parts of request, response or both. These parts could be one or more 168 of the following. 170 o URI - deprecation of one ore more query parameter(s) or path 171 element(s) 173 o method - HTTP method for the resource is deprecated 175 o request header - one or more HTTP request header(s) is deprecated 177 o response header - HTTP response header(s) is deprecated 179 o request body - request body contains one or more deprecated 180 element(s) 182 o response body - response body contains one or more deprecated 183 element(s) 185 The purpose of the "Deprecation" header is to provide just enough 186 "hints" about the deprecation to the client application developer. 187 It is safe to assume that on reception of the "Deprecation" header, 188 the client developer would look up the resource's documentation in 189 order to find deprecation related semantics. The resource developer 190 could provide a link to the resource documentation using a "Link" 191 header with relation type "deprecation" as shown below. 193 Link: ; rel="deprecation"; type="text/html" 195 In this example the interlinked content provides additional 196 information about the deprecation of the resource context. There is 197 no Deprecation header field in the response, and thus the resource is 198 not deprecated. However, the resource already exposes a link where 199 information is available how deprecation is managed for the context. 200 This may be documentation explaining the use of the Deprecation 201 header field, and also explaining under which circumstances and with 202 which policies (announcement before deprecation; continued operation 203 after deprecation) deprecation might be happening. 205 The following example uses the same link header, but also announces a 206 deprecation date using a Deprecation header field. 208 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 209 Link: ; rel="deprecation"; type="text/html" 211 Given that the deprecation date is in the past, the linked resource 212 may have been updated to include information about the deprecation, 213 allowing clients to discover information about the deprecation that 214 happened. 216 4. Recommend Replacement 218 "Link" [RFC8288] header could be used in addition to the 219 "Deprecation" header to recommend the client application about 220 available alternates to the deprecated resource. Following relation 221 types as defined in [RFC8288] are RECOMMENDED to use for the purpose. 223 o "successor-version": Points to a resource containing the successor 224 version. [RFC5829] 226 o "latest-version": Points to a resource containing the latest 227 (e.g., current) version. [RFC5829] 229 o "alternate": Designates a substitute. [W3C.REC-html401-19991224] 231 The following example provides link to the successor version of the 232 requested resource that is deprecated. 234 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 235 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 Sunset HTTP header field [RFC8594] can be used in 248 addition to the "Deprecation" header. 250 The timestamp given in the "Sunset" header field MUST be the later or 251 the same as the one given in the "Deprecation" header field. 253 The following example shows that the resource in context has been 254 deprecated since Sunday, November 11, 2018 at 23:59:59 GMT and its 255 sunset date is Wednesday, November 11, 2020 at 23:59:59 GMT. 257 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 258 Sunset: Wed, 11 Nov 2020 23:59:59 GMT 260 6. Resource Behavior 262 The act of deprecation does not change any behavior of the resource. 263 Deprecated resources SHOULD keep functioning as before, allowing 264 consumers to still use the resources in the same way as they did 265 before the resources were declared deprecated. 267 7. IANA Considerations 269 7.1. The Deprecation HTTP Response Header Field 271 The "Deprecation" response header should be added to the permanent 272 registry of message header fields (see [RFC3864]), taking into 273 account the guidelines given by HTTP/1.1 [RFC7231]. 275 Header Field Name: Deprecation 277 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 279 Status: Standard 281 Author: Sanjay Dalal , 282 Erik Wilde 284 Change controller: IETF 286 Specification document: this specification, 287 Section 2 "The Deprecation HTTP Response Header Field" 289 7.2. The Deprecation Link Relation Type 291 The "deprecation" link relation type should be added to the permanent 292 registry of link relation types according to Section 4.2 of 293 [RFC8288]: 295 Relation Type: deprecation 297 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 299 Status: Standard 301 Author: Sanjay Dalal , 302 Erik Wilde 304 Change controller: IETF 306 Specification document: this specification, 307 Section 3 "The Deprecation Link Relation Type" 309 8. Implementation Status 311 Note to RFC Editor: Please remove this section before publication. 313 This section records the status of known implementations of the 314 protocol defined by this specification at the time of posting of this 315 Internet-Draft, and is based on a proposal described in [RFC7942]. 316 The description of implementations in this section is intended to 317 assist the IETF in its decision processes in progressing drafts to 318 RFCs. Please note that the listing of any individual implementation 319 here does not imply endorsement by the IETF. Furthermore, no effort 320 has been spent to verify the information presented here that was 321 supplied by IETF contributors. This is not intended as, and must not 322 be construed to be, a catalog of available implementations or their 323 features. Readers are advised to note that other implementations may 324 exist. 326 According to RFC 7942, "this will allow reviewers and working groups 327 to assign due consideration to documents that have the benefit of 328 running code, which may serve as evidence of valuable experimentation 329 and feedback that have made the implemented protocols more mature. 330 It is up to the individual working groups to use this information as 331 they see fit". 333 8.1. Implementing the Deprecation Header Field 335 This is a list of implementations that implement the deprecation 336 header field: 338 Organization: Apollo - Description: Deprecation header is returned 339 when deprecated functionality (as declared in the GraphQL schema) is 340 accessed - Reference: https://www.npmjs.com/package/apollo-server- 341 tools 343 8.2. Implementing the Concept 345 This is a list of implementations that implement the general concept, 346 but do so using different mechanisms: 348 Organization: Zapier - Description: Zapier uses two custom HTTP 349 headers named "X-API-Deprecation-Date" and "X-API-Deprecation-Info" - 350 Reference: https://zapier.com/engineering/api-geriatrics/ 352 Organization: IBM - Description: IBM uses a custom HTTP header named 353 "Deprecated" - Reference: 354 https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/ 355 com.ibm.qradar.doc/c_rest_api_getting_started.html 357 Organization: Ultipro - Description: Ultipro uses the HTTP "Warning" 358 header as described in Section 5.5 of [RFC7234] with code "299" - 359 Reference: https://connect.ultipro.com/api-deprecation 361 Organization: Clearbit - Description: Clearbit uses a custom HTTP 362 header named "X-API-Warn" - Reference: https://blog.clearbit.com/ 363 dealing-with-deprecation/ 365 Organization: PayPal - Description: PayPal uses a custom HTTP header 366 named "PayPal-Deprecated" - Reference: https://github.com/paypal/api- 367 standards/blob/master/api-style-guide.md#runtime 369 9. Security Considerations 371 The Deprecation header field SHOULD be treated as a hint, meaning 372 that the resource is indicating (and not guaranteeing with certainty) 373 that it is deprecated. Applications consuming the resource SHOULD 374 check the resource documentation to verify authenticity and accuracy. 375 Resource documentation SHOULD provide additional information about 376 the deprecation including recommendation(s) for replacement. 378 In cases, where the Deprecation header field value is a date in 379 future, it can lead to information that otherwise might not be 380 available. Therefore, applications consuming the resource SHOULD 381 verify the resource documentation and if possible, consult the 382 resource developer to discuss potential impact due to deprecation and 383 plan for possible transition to recommended resource. 385 In cases where "Link" header is used to provide more documentation 386 and/or recommendation for replacement, one should assume that the 387 content of the "Link" header field may not be secure, private or 388 integrity-guaranteed, and due caution should be exercised when using 389 it. Applications consuming the resource SHOULD check the referred 390 resource documentation to verify authenticity and accuracy. 392 The suggested "Link" header fields make extensive use of IRIs and 393 URIs. See [RFC3987] for security considerations relating to IRIs. 394 See [RFC3986] for security considerations relating to URIs. See 395 [RFC7230] for security considerations relating to HTTP headers. 397 Applications that take advantage of typed links should consider the 398 attack vectors opened by automatically following, trusting, or 399 otherwise using links gathered from the HTTP headers. In particular, 400 Link headers that use the "successor-version", "latest-version" or 401 "alternate" relation types should be treated with due caution. See 402 [RFC5829] for security considerations relating to these link relation 403 types. 405 10. Examples 407 The first example shows a deprecation header field without date 408 information: 410 Deprecation: true 412 The second example shows a deprecation header with date information 413 and a link to the successor version: 415 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 416 Link: ; rel="successor-version" 417 The third example shows a deprecation header field with links for the 418 successor version and for the API's deprecation policy. In addition, 419 it shows the sunset date for the deprecated resource: 421 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 422 Sunset: Wed, 11 Nov 2020 23:59:59 GMT 423 Link: ; rel="successor-version", ; rel="deprecation" 425 11. References 427 11.1. Normative References 429 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 430 Requirement Levels", BCP 14, RFC 2119, 431 DOI 10.17487/RFC2119, March 1997, 432 . 434 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 435 Procedures for Message Header Fields", BCP 90, RFC 3864, 436 DOI 10.17487/RFC3864, September 2004, 437 . 439 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 440 Resource Identifier (URI): Generic Syntax", STD 66, 441 RFC 3986, DOI 10.17487/RFC3986, January 2005, 442 . 444 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 445 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 446 January 2005, . 448 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 449 Specifications: ABNF", STD 68, RFC 5234, 450 DOI 10.17487/RFC5234, January 2008, 451 . 453 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 454 Protocol (HTTP/1.1): Message Syntax and Routing", 455 RFC 7230, DOI 10.17487/RFC7230, June 2014, 456 . 458 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 459 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 460 DOI 10.17487/RFC7231, June 2014, 461 . 463 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 464 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 465 RFC 7234, DOI 10.17487/RFC7234, June 2014, 466 . 468 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 469 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 470 May 2017, . 472 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 473 DOI 10.17487/RFC8288, October 2017, 474 . 476 11.2. Informative References 478 [RFC5829] Brown, A., Clemm, G., and J. Reschke, Ed., "Link Relation 479 Types for Simple Version Navigation between Web 480 Resources", RFC 5829, DOI 10.17487/RFC5829, April 2010, 481 . 483 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 484 Code: The Implementation Status Section", BCP 205, 485 RFC 7942, DOI 10.17487/RFC7942, July 2016, 486 . 488 [RFC8594] Wilde, E., "The Sunset HTTP Header Field", RFC 8594, 489 DOI 10.17487/RFC8594, May 2019, 490 . 492 Appendix A. Acknowledgments 494 The authors would like to thank Nikhil Kolekar, Mark Nottingham, and 495 Roberto Polli for their contributions. 497 The authors take all responsibility for errors and omissions. 499 Authors' Addresses 501 Sanjay Dalal 503 Email: sanjay.dalal@cal.berkeley.edu 504 URI: https://github.com/sdatspun2 506 Erik Wilde 508 Email: erik.wilde@dret.net 509 URI: http://dret.net/netdret