idnits 2.17.1 draft-ietf-httpapi-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 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 (July 10, 2021) is 1020 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: 3 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTPAPI S. Dalal 3 Internet-Draft 4 Intended status: Standards Track E. Wilde 5 Expires: January 11, 2022 July 10, 2021 7 The Deprecation HTTP Header Field 8 draft-ietf-httpapi-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 January 11, 2022. 36 Copyright Notice 38 Copyright (c) 2021 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 . . . . . . . . . . . . 3 56 2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 2.2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. The Deprecation Link Relation Type . . . . . . . . . . . . . 4 59 3.1. Documentation . . . . . . . . . . . . . . . . . . . . . . 5 60 4. Recommend Replacement . . . . . . . . . . . . . . . . . . . . 6 61 5. Sunset . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 6. Resource Behavior . . . . . . . . . . . . . . . . . . . . . . 7 63 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 64 7.1. The Deprecation HTTP Response Header . . . . . . . . . . 7 65 7.2. The Deprecation Link Relation Type . . . . . . . . . . . 7 66 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 8 67 8.1. Implementing the Deprecation Header . . . . . . . . . . . 8 68 8.2. Implementing the Concept . . . . . . . . . . . . . . . . 10 69 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 70 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 71 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 72 11.1. Normative References . . . . . . . . . . . . . . . . . . 12 73 11.2. Informative References . . . . . . . . . . . . . . . . . 13 74 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 13 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 77 1. Introduction 79 Deprecation of an HTTP resource as defined in Section 2 of [RFC7231] 80 is a technique to communicate information about the lifecycle of a 81 resource. It encourages applications to migrate away from the 82 resource, discourages applications from forming new dependencies on 83 the resource, and informs applications about the risk of continuing 84 dependence upon the resource. 86 The act of deprecation does not change any behavior of the resource. 87 It just informs client of the fact that a resource is deprecated. 88 The Deprecation HTTP response header field MAY be used to convey this 89 fact at runtime to clients. The header field can carry information 90 indicating since when the deprecation is in effect. 92 In addition to the Deprecation header field the resource provider can 93 use other header fields to convey additional information related to 94 deprecation. For example, information such as where to find 95 documentation related to the deprecation or what should be used as an 96 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 The term "resource" is to be interpreted as defined in Section 2 of 113 [RFC7231], that is identified by an URI. 115 2. The Deprecation HTTP Response Header 117 The "Deprecation" HTTP response header field allows a server to 118 communicate to a client that the resource in context of the message 119 is or will be deprecated. 121 2.1. Syntax 123 The "Deprecation" response header field describes the deprecation. 124 It either shows the deprecation date, which may be in the future (the 125 resource context will be deprecated at that date) or in the past (the 126 resource context has been deprecated at that date), or it simply 127 flags the resource context as being deprecated: 129 Deprecation = IMF-fixdate / "true" 131 Servers MUST NOT include more than one "Deprecation" header field in 132 the same response. 134 The date, if present, is the date when the resource context was or 135 will be deprecated. It is in the form of an IMF-fixdate timestamp. 137 The following example shows that the resource context has been 138 deprecated on Sunday, November 11, 2018 at 23:59:59 GMT: 140 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 141 The deprecation date can be in the future. If the value of "date" is 142 in the future, it means that the resource will be deprecated at the 143 given date in future. 145 If the deprecation date is not known, the header field can carry the 146 simple string "true", indicating that the resource context is 147 deprecated, without indicating when that happened: 149 Deprecation: true 151 2.2. Scope 153 The Deprecation header field applies to the resource that returns it, 154 meaning that it announces the upcoming deprecation of that specific 155 resource. However, there may be scenarios where the scope of the 156 announced deprecation is larger than just the single resource where 157 it appears. 159 Resources are free to define such an increased scope, and usually 160 this scope will be documented by the resource so that consumers of 161 the resource know about the increased scope and can behave 162 accordingly. However, it is important to take into account that such 163 increased scoping is invisible for consumers who are unaware of the 164 increased scoping rules. This means that these consumers will not be 165 aware of the increased scope, and they will not interpret Deprecation 166 information different from its standard meaning (i.e., it applies to 167 the resource only). 169 Using such an increased scope still may make sense, as Deprecation 170 information is only a hint anyway; thus, it is optional information 171 that cannot be depended on, and clients should always be implemented 172 in ways that allow them to function without Deprecation information. 173 Increased scope information may help clients to glean additional 174 hints from resources and, thus, might allow them to implement 175 behavior that allows them to make educated guesses about resources 176 becoming deprecated. 178 3. The Deprecation Link Relation Type 180 In addition to the Deprecation HTTP header field, the server can use 181 links with the "deprecation" link relation type to communicate to the 182 client where to find more information about deprecation of the 183 context. This can happen before the actual deprecation, to make a 184 deprecation policy discoverable, or after deprecation, when there may 185 be documentation about the deprecation, and possibly documentation of 186 how to manage it. 188 This specification places no restrictions on the representation of 189 the interlinked deprecation policy. In particular, the deprecation 190 policy may be available as human-readable documentation or as 191 machine-readable description. 193 3.1. Documentation 195 For a resource, deprecation could involve one or more parts of 196 request, response or both. These parts could be one or more of the 197 following. 199 o URI - deprecation of one ore more query parameter(s) or path 200 element(s) 202 o method - HTTP method for the resource is deprecated 204 o request header - one or more HTTP request header(s) is deprecated 206 o response header - HTTP response header(s) is deprecated 208 o request body - request body contains one or more deprecated 209 element(s) 211 o response body - response body contains one or more deprecated 212 element(s) 214 The purpose of the "Deprecation" header is to provide just enough 215 "hints" about the deprecation to the client application developer. 216 It is safe to assume that on reception of the "Deprecation" header, 217 the client developer would look up the resource's documentation in 218 order to find deprecation related semantics. The resource developer 219 could provide a link to the resource documentation using a "Link" 220 header with relation type "deprecation" as shown below. 222 Link: ; 223 rel="deprecation"; type="text/html" 225 In this example the interlinked content provides additional 226 information about the deprecation of the resource context. There is 227 no Deprecation header field in the response, and thus the resource is 228 not deprecated. However, the resource already exposes a link where 229 information is available how deprecation is managed for the context. 230 This may be documentation explaining the use of the Deprecation 231 header field, and also explaining under which circumstances and with 232 which policies (announcement before deprecation; continued operation 233 after deprecation) deprecation might be happening. 235 The following example uses the same link header, but also announces a 236 deprecation date using a Deprecation header field. 238 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 239 Link: ; 240 rel="deprecation"; type="text/html" 242 Given that the deprecation date is in the past, the linked resource 243 may have been updated to include information about the deprecation, 244 allowing clients to discover information about the deprecation that 245 happened. 247 4. Recommend Replacement 249 The "Link" [RFC8288] header field can be used in addition to the 250 "Deprecation" header field to inform the client about available 251 alternatives to the deprecated resource. The following relation 252 types as defined in [RFC8288] are RECOMMENDED to use for this 253 purpose: 255 o "successor-version": Points to a resource containing the successor 256 version. [RFC5829] 258 o "latest-version": Points to a resource containing the latest 259 (e.g., current) version. [RFC5829] 261 o "alternate": Designates a substitute. [W3C.REC-html401-19991224] 263 The following example provides link to the successor version of the 264 requested resource that is deprecated. 266 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 267 Link: ; rel="successor-version" 269 This example provides link to an alternate resource to the requested 270 resource that is deprecated. 272 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 273 Link: ; rel="alternate" 275 5. Sunset 277 In addition to the deprecation related information, if the resource 278 provider wants to convey to the client application that the 279 deprecated resource is expected to become unresponsive at a specific 280 point in time, the Sunset HTTP header field [RFC8594] can be used in 281 addition to the "Deprecation" header. 283 The timestamp given in the "Sunset" header field MUST be the later or 284 the same as the one given in the "Deprecation" header field. 286 The following example shows that the resource in context has been 287 deprecated since Sunday, November 11, 2018 at 23:59:59 GMT and its 288 sunset date is Wednesday, November 11, 2020 at 23:59:59 GMT. 290 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 291 Sunset: Wed, 11 Nov 2020 23:59:59 GMT 293 6. Resource Behavior 295 The act of deprecation does not change any behavior of the resource. 296 Deprecated resources SHOULD keep functioning as before, allowing 297 consumers to still use the resources in the same way as they did 298 before the resources were declared deprecated. 300 7. IANA Considerations 302 7.1. The Deprecation HTTP Response Header 304 The "Deprecation" response header should be added to the permanent 305 registry of message header fields (see [RFC3864]), taking into 306 account the guidelines given by HTTP/1.1 [RFC7231]. 308 Header Field Name: Deprecation 310 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 312 Status: Standard 314 Author: Sanjay Dalal , 315 Erik Wilde 317 Change controller: IETF 319 Specification document: this specification, 320 Section 2 "The Deprecation HTTP Response Header" 322 7.2. The Deprecation Link Relation Type 324 The "deprecation" link relation type should be added to the permanent 325 registry of link relation types according to Section 4.2 of 326 [RFC8288]: 328 Relation Type: deprecation 330 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 332 Status: Standard 334 Author: Sanjay Dalal , 335 Erik Wilde 337 Change controller: IETF 339 Specification document: this specification, 340 Section 3 "The Deprecation Link Relation Type" 342 8. Implementation Status 344 Note to RFC Editor: Please remove this section before publication. 346 This section records the status of known implementations of the 347 protocol defined by this specification at the time of posting of this 348 Internet-Draft, and is based on a proposal described in [RFC7942]. 349 The description of implementations in this section is intended to 350 assist the IETF in its decision processes in progressing drafts to 351 RFCs. Please note that the listing of any individual implementation 352 here does not imply endorsement by the IETF. Furthermore, no effort 353 has been spent to verify the information presented here that was 354 supplied by IETF contributors. This is not intended as, and must not 355 be construed to be, a catalog of available implementations or their 356 features. Readers are advised to note that other implementations may 357 exist. 359 According to RFC 7942, "this will allow reviewers and working groups 360 to assign due consideration to documents that have the benefit of 361 running code, which may serve as evidence of valuable experimentation 362 and feedback that have made the implemented protocols more mature. 363 It is up to the individual working groups to use this information as 364 they see fit". 366 8.1. Implementing the Deprecation Header 368 This is a list of implementations that implement the deprecation 369 header field: 371 Organization: Apollo 373 o Description: Deprecation header is returned when deprecated 374 functionality (as declared in the GraphQL schema) is accessed 376 o Reference: https://www.npmjs.com/package/apollo-server-tools 378 Organization: Zalando 380 o Description: Deprecation header is recommended as the preferred 381 way to communicate API deprecation in Zalando API designs. 383 o Reference: https://opensource.zalando.com/restful-api- 384 guidelines/#deprecation 386 Organization: Palantir Technologies 388 o Description: Deprecation header is incorporated in code generated 389 by conjure-java, a CLI to generate Java POJOs and interfaces from 390 Conjure API definitions 392 o Reference: https://github.com/palantir/conjure-java 394 Organization: IETF Internet Draft, Registration Protocols Extensions 396 o Description: Deprecation link relation is returned in Registration 397 Data Access Protocol (RDAP) notices to indicate deprecation of 398 jCard in favor of JSContact. 400 o Reference: https://tools.ietf.org/html/draft-loffredo-regext-rdap- 401 jcard-deprecation 403 Organization: E-Voyageurs Technologies 405 o Description: Deprecation header is incorporated in Hesperides, a 406 configuration management tool providing universal text file 407 templating and properties editing through a REST API or a webapp. 409 o Reference: https://github.com/voyages-sncf- 410 technologies/hesperides/blob/master/documentation/lightweight- 411 architecture-decision-records/deprecated_endpoints.md 413 Organization: Open-Xchange 415 o Description: Deprecation header is used in Open-Xchange appsuite- 416 middleware 418 o Reference: https://github.com/open-xchange/appsuite-middleware 420 Organization: MediaWiki 421 o Description: Core REST API of MediaWiki would use Deprecation 422 header for endpoints that have been deprecated because a new 423 endpoint provides the same or better functionality. 425 o Reference: https://phabricator.wikimedia.org/T232485 427 8.2. Implementing the Concept 429 This is a list of implementations that implement the general concept, 430 but do so using different mechanisms: 432 Organization: Zapier 434 o Description: Zapier uses two custom HTTP headers named "X-API- 435 Deprecation-Date" and "X-API-Deprecation-Info" 437 o Reference: https://zapier.com/engineering/api-geriatrics/ 439 Organization: IBM 441 o Description: IBM uses a custom HTTP header named "Deprecated" 443 o Reference: 444 https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/ 445 com.ibm.qradar.doc/c_rest_api_getting_started.html 447 Organization: Ultipro 449 o Description: Ultipro uses the HTTP "Warning" header as described 450 in Section 5.5 of [RFC7234] with code "299" 452 o Reference: https://connect.ultipro.com/api-deprecation 454 Organization: Clearbit 456 o Description: Clearbit uses a custom HTTP header named "X-API-Warn" 458 o Reference: https://blog.clearbit.com/dealing-with-deprecation/ 460 Organization: PayPal 462 o Description: PayPal uses a custom HTTP header named "PayPal- 463 Deprecated" 465 o Reference: https://github.com/paypal/api-standards/blob/master/ 466 api-style-guide.md#runtime 468 9. Security Considerations 470 The Deprecation header field SHOULD be treated as a hint, meaning 471 that the resource is indicating (and not guaranteeing with certainty) 472 that it is deprecated. Applications consuming the resource SHOULD 473 check the resource documentation to verify authenticity and accuracy. 474 Resource documentation SHOULD provide additional information about 475 the deprecation including recommendation(s) for replacement. 477 In cases, where the Deprecation header field value is a date in 478 future, it can lead to information that otherwise might not be 479 available. Therefore, applications consuming the resource SHOULD 480 verify the resource documentation and if possible, consult the 481 resource developer to discuss potential impact due to deprecation and 482 plan for possible transition to recommended resource. 484 In cases where "Link" header is used to provide more documentation 485 and/or recommendation for replacement, one should assume that the 486 content of the "Link" header field may not be secure, private or 487 integrity-guaranteed, and due caution should be exercised when using 488 it. Applications consuming the resource SHOULD check the referred 489 resource documentation to verify authenticity and accuracy. 491 The suggested "Link" header fields make extensive use of IRIs and 492 URIs. See [RFC3987] for security considerations relating to IRIs. 493 See [RFC3986] for security considerations relating to URIs. See 494 [RFC7230] for security considerations relating to HTTP headers. 496 Applications that take advantage of typed links should consider the 497 attack vectors opened by automatically following, trusting, or 498 otherwise using links gathered from the HTTP headers. In particular, 499 Link headers that use the "successor-version", "latest-version" or 500 "alternate" relation types should be treated with due caution. See 501 [RFC5829] for security considerations relating to these link relation 502 types. 504 10. Examples 506 The first example shows a deprecation header field without date 507 information: 509 Deprecation: true 511 The second example shows a deprecation header with date information 512 and a link to the successor version: 514 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 515 Link: ; rel="successor-version" 516 The third example shows a deprecation header field with links for the 517 successor version and for the API's deprecation policy. In addition, 518 it shows the sunset date for the deprecated resource: 520 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 521 Sunset: Wed, 11 Nov 2020 23:59:59 GMT 522 Link: ; rel="successor-version", 523 ; rel="deprecation" 525 11. References 527 11.1. Normative References 529 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 530 Requirement Levels", BCP 14, RFC 2119, 531 DOI 10.17487/RFC2119, March 1997, 532 . 534 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 535 Procedures for Message Header Fields", BCP 90, RFC 3864, 536 DOI 10.17487/RFC3864, September 2004, 537 . 539 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 540 Resource Identifier (URI): Generic Syntax", STD 66, 541 RFC 3986, DOI 10.17487/RFC3986, January 2005, 542 . 544 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 545 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 546 January 2005, . 548 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 549 Specifications: ABNF", STD 68, RFC 5234, 550 DOI 10.17487/RFC5234, January 2008, 551 . 553 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 554 Protocol (HTTP/1.1): Message Syntax and Routing", 555 RFC 7230, DOI 10.17487/RFC7230, June 2014, 556 . 558 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 559 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 560 DOI 10.17487/RFC7231, June 2014, 561 . 563 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 564 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 565 RFC 7234, DOI 10.17487/RFC7234, June 2014, 566 . 568 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 569 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 570 May 2017, . 572 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 573 DOI 10.17487/RFC8288, October 2017, 574 . 576 11.2. Informative References 578 [RFC5829] Brown, A., Clemm, G., and J. Reschke, Ed., "Link Relation 579 Types for Simple Version Navigation between Web 580 Resources", RFC 5829, DOI 10.17487/RFC5829, April 2010, 581 . 583 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 584 Code: The Implementation Status Section", BCP 205, 585 RFC 7942, DOI 10.17487/RFC7942, July 2016, 586 . 588 [RFC8594] Wilde, E., "The Sunset HTTP Header Field", RFC 8594, 589 DOI 10.17487/RFC8594, May 2019, 590 . 592 [W3C.REC-html401-19991224] 593 Raggett, D., Hors, A., and I. Jacobs, "HTML 4.01 594 Specification", World Wide Web Consortium Recommendation 595 REC-html401-19991224, December 1999, 596 . 598 Appendix A. Acknowledgments 600 The authors would like to thank Nikhil Kolekar, Darrel Miller, Mark 601 Nottingham, and Roberto Polli for their contributions. 603 The authors take all responsibility for errors and omissions. 605 Authors' Addresses 607 Sanjay Dalal 609 Email: sanjay.dalal@cal.berkeley.edu 610 URI: https://github.com/sdatspun2 611 Erik Wilde 613 Email: erik.wilde@dret.net 614 URI: http://dret.net/netdret