idnits 2.17.1 draft-ietf-httpapi-deprecation-header-00.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 (23 December 2020) is 1220 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: 26 June 2021 23 December 2020 7 The Deprecation HTTP Header 8 draft-ietf-httpapi-deprecation-header-00 10 Abstract 12 The HTTP Deprecation Response Header 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 26 June 2021. 36 Copyright Notice 38 Copyright (c) 2020 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 (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 54 2. The Deprecation HTTP Response Header . . . . . . . . . . . . 3 55 2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 3. The Deprecation Link Relation Type . . . . . . . . . . . . . 4 57 3.1. Documentation . . . . . . . . . . . . . . . . . . . . . . 4 58 4. Recommend Replacement . . . . . . . . . . . . . . . . . . . . 5 59 5. Sunset . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 60 6. Resource Behavior . . . . . . . . . . . . . . . . . . . . . . 6 61 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 62 7.1. The Deprecation HTTP Response Header . . . . . . . . . . 6 63 7.2. The Deprecation Link Relation Type . . . . . . . . . . . 7 64 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 7 65 8.1. Implementing the Deprecation Header . . . . . . . . . . . 8 66 8.2. Implementing the Concept . . . . . . . . . . . . . . . . 9 67 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 68 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 70 11.1. Normative References . . . . . . . . . . . . . . . . . . 11 71 11.2. Informative References . . . . . . . . . . . . . . . . . 12 72 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 13 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 75 1. Introduction 77 Deprecation of an HTTP resource as defined in Section 2 of [RFC7231] 78 is a technique to communicate information about the lifecycle of a 79 resource. It encourages applications to migrate away from the 80 resource, discourages applications from forming new dependencies on 81 the resource, and informs applications about the risk of continuing 82 dependence upon the resource. 84 The act of deprecation does not change any behavior of the resource. 85 It just informs client of the fact that a resource is deprecated. 86 The Deprecation HTTP response header field MAY be used to convey this 87 fact at runtime to clients. The header field can carry information 88 indicating since when the deprecation is in effect. 90 In addition to the Deprecation header field the resource provider can 91 use other header fields to convey additional information related to 92 deprecation. For example, information such as where to find 93 documentation related to the deprecation or what should be used as an 94 alternate and when the deprecated resource would be unreachable, etc. 95 Alternates of a resource can be similar resource(s) or a newer 96 version of the same resource. 98 1.1. Notational Conventions 100 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 101 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 102 "OPTIONAL" in this document are to be interpreted as described in BCP 103 14 [RFC2119] [RFC8174] when, and only when, they appear in all 104 capitals, as shown here. 106 This specification uses the Augmented Backus-Naur Form (ABNF) 107 notation of [RFC5234] and includes, by reference, the IMF-fixdate 108 rule as defined in Section 7.1.1.1 of [RFC7231]. 110 The term "resource" is to be interpreted as defined in Section 2 of 111 [RFC7231], that is identified by an URI. 113 2. The Deprecation HTTP Response Header 115 The "Deprecation" HTTP response header field allows a server to 116 communicate to a client that the resource in context of the message 117 is or will be deprecated. 119 2.1. Syntax 121 The "Deprecation" response header field describes the deprecation. 122 It either shows the deprecation date, which may be in the future (the 123 resource context will be deprecated at that date) or in the past (the 124 resource context has been deprecated at that date), or it simply 125 flags the resource context as being deprecated: 127 Deprecation = IMF-fixdate / "true" 129 Servers MUST NOT include more than one "Deprecation" header field in 130 the same response. 132 The date, if present, is the date when the resource context was or 133 will be deprecated. It is in the form of an IMF-fixdate timestamp. 135 The following example shows that the resource context has been 136 deprecated on Friday, November 11, 2018 at 23:59:59 GMT: 138 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 140 The deprecation date can be in the future. If the value of "date" is 141 in the future, it means that the resource will be deprecated at the 142 given date in future. 144 If the deprecation date is not known, the header field can carry the 145 simple string "true", indicating that the resource context is 146 deprecated, without indicating when that happened: 148 Deprecation: true 150 3. The Deprecation Link Relation Type 152 In addition to the Deprecation HTTP header field, the server can use 153 links with the "deprecation" link relation type to communicate to the 154 client where to find more information about deprecation of the 155 context. This can happen before the actual deprecation, to make a 156 deprecation policy discoverable, or after deprecation, when there may 157 be documentation about the deprecation, and possibly documentation of 158 how to manage it. 160 This specification places no restrictions on the representation of 161 the interlinked deprecation policy. In particular, the deprecation 162 policy may be available as human-readable documentation or as 163 machine-readable description. 165 3.1. Documentation 167 For a resource, deprecation could involve one or more parts of 168 request, response or both. These parts could be one or more of the 169 following. 171 * URI - deprecation of one ore more query parameter(s) or path 172 element(s) 174 * method - HTTP method for the resource is deprecated 176 * request header - one or more HTTP request header(s) is deprecated 178 * response header - HTTP response header(s) is deprecated 180 * request body - request body contains one or more deprecated 181 element(s) 183 * response body - response body contains one or more deprecated 184 element(s) 186 The purpose of the "Deprecation" header is to provide just enough 187 "hints" about the deprecation to the client application developer. 188 It is safe to assume that on reception of the "Deprecation" header, 189 the client developer would look up the resource's documentation in 190 order to find deprecation related semantics. The resource developer 191 could provide a link to the resource documentation using a "Link" 192 header with relation type "deprecation" as shown below. 194 Link: ; 195 rel="deprecation"; type="text/html" 197 In this example the interlinked content provides additional 198 information about the deprecation of the resource context. There is 199 no Deprecation header field in the response, and thus the resource is 200 not deprecated. However, the resource already exposes a link where 201 information is available how deprecation is managed for the context. 202 This may be documentation explaining the use of the Deprecation 203 header field, and also explaining under which circumstances and with 204 which policies (announcement before deprecation; continued operation 205 after deprecation) deprecation might be happening. 207 The following example uses the same link header, but also announces a 208 deprecation date using a Deprecation header field. 210 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 211 Link: ; 212 rel="deprecation"; type="text/html" 214 Given that the deprecation date is in the past, the linked resource 215 may have been updated to include information about the deprecation, 216 allowing clients to discover information about the deprecation that 217 happened. 219 4. Recommend Replacement 221 The "Link" [RFC8288] header field can be used in addition to the 222 "Deprecation" header field to inform the client about available 223 alternatives to the deprecated resource. The following relation 224 types as defined in [RFC8288] are RECOMMENDED to use for this 225 purpose: 227 * "successor-version": Points to a resource containing the successor 228 version. [RFC5829] 230 * "latest-version": Points to a resource containing the latest 231 (e.g., current) version. [RFC5829] 233 * "alternate": Designates a substitute. [W3C.REC-html401-19991224] 234 The following example provides link to the successor version of the 235 requested resource that is deprecated. 237 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 238 Link: ; rel="successor-version" 240 This example provides link to an alternate resource to the requested 241 resource that is deprecated. 243 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 244 Link: ; rel="alternate" 246 5. Sunset 248 In addition to the deprecation related information, if the resource 249 provider wants to convey to the client application that the 250 deprecated resource is expected to become unresponsive at a specific 251 point in time, the Sunset HTTP header field [RFC8594] can be used in 252 addition to the "Deprecation" header. 254 The timestamp given in the "Sunset" header field MUST be the later or 255 the same as the one given in the "Deprecation" header field. 257 The following example shows that the resource in context has been 258 deprecated since Sunday, November 11, 2018 at 23:59:59 GMT and its 259 sunset date is Wednesday, November 11, 2020 at 23:59:59 GMT. 261 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 262 Sunset: Wed, 11 Nov 2020 23:59:59 GMT 264 6. Resource Behavior 266 The act of deprecation does not change any behavior of the resource. 267 Deprecated resources SHOULD keep functioning as before, allowing 268 consumers to still use the resources in the same way as they did 269 before the resources were declared deprecated. 271 7. IANA Considerations 273 7.1. The Deprecation HTTP Response Header 275 The "Deprecation" response header should be added to the permanent 276 registry of message header fields (see [RFC3864]), taking into 277 account the guidelines given by HTTP/1.1 [RFC7231]. 279 Header Field Name: Deprecation 281 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 283 Status: Standard 285 Author: Sanjay Dalal , 286 Erik Wilde 288 Change controller: IETF 290 Specification document: this specification, 291 Section 2 "The Deprecation HTTP Response Header" 293 7.2. The Deprecation Link Relation Type 295 The "deprecation" link relation type should be added to the permanent 296 registry of link relation types according to Section 4.2 of 297 [RFC8288]: 299 Relation Type: deprecation 301 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 303 Status: Standard 305 Author: Sanjay Dalal , 306 Erik Wilde 308 Change controller: IETF 310 Specification document: this specification, 311 Section 3 "The Deprecation Link Relation Type" 313 8. Implementation Status 315 Note to RFC Editor: Please remove this section before publication. 317 This section records the status of known implementations of the 318 protocol defined by this specification at the time of posting of this 319 Internet-Draft, and is based on a proposal described in [RFC7942]. 320 The description of implementations in this section is intended to 321 assist the IETF in its decision processes in progressing drafts to 322 RFCs. Please note that the listing of any individual implementation 323 here does not imply endorsement by the IETF. Furthermore, no effort 324 has been spent to verify the information presented here that was 325 supplied by IETF contributors. This is not intended as, and must not 326 be construed to be, a catalog of available implementations or their 327 features. Readers are advised to note that other implementations may 328 exist. 330 According to RFC 7942, "this will allow reviewers and working groups 331 to assign due consideration to documents that have the benefit of 332 running code, which may serve as evidence of valuable experimentation 333 and feedback that have made the implemented protocols more mature. 334 It is up to the individual working groups to use this information as 335 they see fit". 337 8.1. Implementing the Deprecation Header 339 This is a list of implementations that implement the deprecation 340 header field: 342 Organization: Apollo 344 * Description: Deprecation header is returned when deprecated 345 functionality (as declared in the GraphQL schema) is accessed 347 * Reference: https://www.npmjs.com/package/apollo-server-tools 349 Organization: Zalando 351 * Description: Deprecation header is recommended as the preferred 352 way to communicate API deprecation in Zalando API designs. 354 * Reference: https://opensource.zalando.com/restful-api- 355 guidelines/#deprecation 357 Organization: Palantir Technologies 359 * Description: Deprecation header is incorporated in code generated 360 by conjure-java, a CLI to generate Java POJOs and interfaces from 361 Conjure API definitions 363 * Reference: https://github.com/palantir/conjure-java 364 Organization: IETF Internet Draft, Registration Protocols Extensions 366 * Description: Deprecation link relation is returned in Registration 367 Data Access Protocol (RDAP) notices to indicate deprecation of 368 jCard in favor of JSContact. 370 * Reference: https://tools.ietf.org/html/draft-loffredo-regext-rdap- 371 jcard-deprecation 373 Organization: E-Voyageurs Technologies 375 * Description: Deprecation header is incorporated in Hesperides, a 376 configuration management tool providing universal text file 377 templating and properties editing through a REST API or a webapp. 379 * Reference: https://github.com/voyages-sncf- 380 technologies/hesperides/blob/master/documentation/lightweight- 381 architecture-decision-records/deprecated_endpoints.md 383 Organization: Open-Xchange 385 * Description: Deprecation header is used in Open-Xchange appsuite- 386 middleware 388 * Reference: https://github.com/open-xchange/appsuite-middleware 390 Organization: MediaWiki 392 * Description: Core REST API of MediaWiki would use Deprecation 393 header for endpoints that have been deprecated because a new 394 endpoint provides the same or better functionality. 396 * Reference: https://phabricator.wikimedia.org/T232485 398 8.2. Implementing the Concept 400 This is a list of implementations that implement the general concept, 401 but do so using different mechanisms: 403 Organization: Zapier 405 * Description: Zapier uses two custom HTTP headers named "X-API- 406 Deprecation-Date" and "X-API-Deprecation-Info" 408 * Reference: https://zapier.com/engineering/api-geriatrics/ 410 Organization: IBM 411 * Description: IBM uses a custom HTTP header named "Deprecated" 413 * Reference: 414 https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/ 415 com.ibm.qradar.doc/c_rest_api_getting_started.html 417 Organization: Ultipro 419 * Description: Ultipro uses the HTTP "Warning" header as described 420 in Section 5.5 of [RFC7234] with code "299" 422 * Reference: https://connect.ultipro.com/api-deprecation 424 Organization: Clearbit 426 * Description: Clearbit uses a custom HTTP header named "X-API-Warn" 428 * Reference: https://blog.clearbit.com/dealing-with-deprecation/ 430 Organization: PayPal 432 * Description: PayPal uses a custom HTTP header named "PayPal- 433 Deprecated" 435 * Reference: https://github.com/paypal/api-standards/blob/master/ 436 api-style-guide.md#runtime 438 9. Security Considerations 440 The Deprecation header field SHOULD be treated as a hint, meaning 441 that the resource is indicating (and not guaranteeing with certainty) 442 that it is deprecated. Applications consuming the resource SHOULD 443 check the resource documentation to verify authenticity and accuracy. 444 Resource documentation SHOULD provide additional information about 445 the deprecation including recommendation(s) for replacement. 447 In cases, where the Deprecation header field value is a date in 448 future, it can lead to information that otherwise might not be 449 available. Therefore, applications consuming the resource SHOULD 450 verify the resource documentation and if possible, consult the 451 resource developer to discuss potential impact due to deprecation and 452 plan for possible transition to recommended resource. 454 In cases where "Link" header is used to provide more documentation 455 and/or recommendation for replacement, one should assume that the 456 content of the "Link" header field may not be secure, private or 457 integrity-guaranteed, and due caution should be exercised when using 458 it. Applications consuming the resource SHOULD check the referred 459 resource documentation to verify authenticity and accuracy. 461 The suggested "Link" header fields make extensive use of IRIs and 462 URIs. See [RFC3987] for security considerations relating to IRIs. 463 See [RFC3986] for security considerations relating to URIs. See 464 [RFC7230] for security considerations relating to HTTP headers. 466 Applications that take advantage of typed links should consider the 467 attack vectors opened by automatically following, trusting, or 468 otherwise using links gathered from the HTTP headers. In particular, 469 Link headers that use the "successor-version", "latest-version" or 470 "alternate" relation types should be treated with due caution. See 471 [RFC5829] for security considerations relating to these link relation 472 types. 474 10. Examples 476 The first example shows a deprecation header field without date 477 information: 479 Deprecation: true 481 The second example shows a deprecation header with date information 482 and a link to the successor version: 484 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 485 Link: ; rel="successor-version" 487 The third example shows a deprecation header field with links for the 488 successor version and for the API's deprecation policy. In addition, 489 it shows the sunset date for the deprecated resource: 491 Deprecation: Sun, 11 Nov 2018 23:59:59 GMT 492 Sunset: Wed, 11 Nov 2020 23:59:59 GMT 493 Link: ; rel="successor-version", 494 ; rel="deprecation" 496 11. References 498 11.1. Normative References 500 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 501 Requirement Levels", BCP 14, RFC 2119, 502 DOI 10.17487/RFC2119, March 1997, 503 . 505 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 506 Procedures for Message Header Fields", BCP 90, RFC 3864, 507 DOI 10.17487/RFC3864, September 2004, 508 . 510 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 511 Resource Identifier (URI): Generic Syntax", STD 66, 512 RFC 3986, DOI 10.17487/RFC3986, January 2005, 513 . 515 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 516 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 517 January 2005, . 519 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 520 Specifications: ABNF", STD 68, RFC 5234, 521 DOI 10.17487/RFC5234, January 2008, 522 . 524 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 525 Protocol (HTTP/1.1): Message Syntax and Routing", 526 RFC 7230, DOI 10.17487/RFC7230, June 2014, 527 . 529 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 530 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 531 DOI 10.17487/RFC7231, June 2014, 532 . 534 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 535 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 536 RFC 7234, DOI 10.17487/RFC7234, June 2014, 537 . 539 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 540 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 541 May 2017, . 543 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 544 DOI 10.17487/RFC8288, October 2017, 545 . 547 11.2. Informative References 549 [RFC5829] Brown, A., Clemm, G., and J. Reschke, Ed., "Link Relation 550 Types for Simple Version Navigation between Web 551 Resources", RFC 5829, DOI 10.17487/RFC5829, April 2010, 552 . 554 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 555 Code: The Implementation Status Section", BCP 205, 556 RFC 7942, DOI 10.17487/RFC7942, July 2016, 557 . 559 [RFC8594] Wilde, E., "The Sunset HTTP Header Field", RFC 8594, 560 DOI 10.17487/RFC8594, May 2019, 561 . 563 Appendix A. Acknowledgments 565 The authors would like to thank Nikhil Kolekar, Mark Nottingham, and 566 Roberto Polli for their contributions. 568 The authors take all responsibility for errors and omissions. 570 Authors' Addresses 572 Sanjay Dalal 574 Email: sanjay.dalal@cal.berkeley.edu 575 URI: https://github.com/sdatspun2 577 Erik Wilde 579 Email: erik.wilde@dret.net 580 URI: http://dret.net/netdret