idnits 2.17.1 draft-dalal-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 (February 26, 2019) is 1885 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) == Unused Reference: 'Deprecation' is defined on line 495, but no explicit reference was found in the text ** 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 (~~), 3 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: August 30, 2019 February 26, 2019 7 The Deprecation HTTP Header 8 draft-dalal-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 use of the resource 14 has been deprecated. Additionally, the deprecation link relation can 15 be used to link to a resource that provides additional context for 16 the 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 August 30, 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 2.1.1. Version . . . . . . . . . . . . . . . . . . . . . . . 4 58 2.1.2. Date . . . . . . . . . . . . . . . . . . . . . . . . 4 59 3. The Deprecation Link Relation Type . . . . . . . . . . . . . 5 60 3.1. Documentation . . . . . . . . . . . . . . . . . . . . . . 5 61 3.2. Policy . . . . . . . . . . . . . . . . . . . . . . . . . 6 62 4. Recommend Replacement . . . . . . . . . . . . . . . . . . . . 6 63 5. Sunset . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 64 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 65 6.1. The Deprecation Response Header Field . . . . . . . . . . 7 66 6.2. The Deprecation Link Relation Type . . . . . . . . . . . 7 67 7. Implementation Status . . . . . . . . . . . . . . . . . . . . 8 68 8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 69 9. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 71 10.1. Normative References . . . . . . . . . . . . . . . . . . 10 72 10.2. Informative References . . . . . . . . . . . . . . . . . 11 73 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 11 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 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 and 81 discourage applications from forming new dependencies on the 82 resource, and informs applications of 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 additional 89 information such as 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 "token" rule, 110 DQUOTE (double quote) rule, the SP (space) rule and the "rule" 111 extension that allows for compact definition of comma-separated lists 112 using a '#' operator (similar to how the '*' operator indicates 113 repetition), HTTP-date rule as defined within Sections 3.2.6 and 7 of 114 [RFC7230] and Section 7.1.1 of [RFC7231]. 116 2. The Deprecation HTTP Response Header Field 118 The "Deprecation" HTTP response header field allows a server to 119 communicate to a client that the URI-identified resource in context 120 of the message is deprecated. It can also provide information that 121 the resource is deprecated since which version. 123 2.1. Syntax 125 The "Deprecation" response header contains the header name 126 "Deprecation" followed by a ":" and a property(s). Each property 127 consists of a name-value-pair. Servers SHOULD NOT send Deprecation 128 headers that fail to conform to the following grammar: 130 deprecation-header = "Deprecation:" SP "version"=vval, "date"=dval, 131 *( extension ) 132 extension = property-name "=" property-value 133 property-name = DQUOTE token DQUOTE 134 token = 135 vval = property-value 136 property-value = DQUOTE *( pchar ) DQUOTE 137 pchar = %x23 / %x2B-3A / %x41-5A / %x61-7A / %x7C 138 ; US-ASCII characters 139 dval = DQUOTE HTTP-date DQUOTE 141 Note that some of the grammatical terms above reference documents 142 that use different grammatical notations than this document (which 143 uses ABNF from [RFC5234]). 145 Servers SHOULD NOT include more than one "Deprecation" header field 146 in the same response. If a server sends multiple responses 147 containing "Deprecation" headers concurrently to the user agent 148 (e.g., when communicating with the user agent over multiple sockets), 149 these responses create a "race condition" that can lead to 150 unpredictable behavior. 152 The value of "Deprecation" response header field could consist of at 153 least 1 standard property: "date" or "version" as shown below. 154 Either of "version" or "date" is REQUIRED and both are also allowed. 156 Deprecation: version="version", date="date" 158 2.1.1. Version 160 The value of the "version" property, if present, could be the version 161 of the resource that is deprecated. The value of "version" would be 162 an opaque version identifier. For resources that use date-based 163 versioning scheme, the value would be accordingly. 165 Following example indicates that the version v1 of the resource in 166 context is deprecated. 168 Deprecation: version="v1" 170 Following example shows that the version 2018-11-08 (November 8, 171 2018) of the resource in context is deprecated. Here the versioning 172 scheme used is date-based. 174 Deprecation: version="2018-11-08" 176 2.1.2. Date 178 The value of "date" property, if present, would be the date when 179 resource was deprecated. It would be in the form of a quoted HTTP- 180 date timestamp, as defined in Section 7.1.1.1 of [RFC7231]. 182 Following example shows that the resource in context is deprecated on 183 Friday, November 11, 2018 at 23:59:59 GMT. 185 Deprecation: date="Fri, 11 Nov 2018 23:59:59 GMT" 187 Date could be in future too. If the value of "date" is in future, it 188 means that the resource would be deprecated on the given date in 189 future. 191 3. The Deprecation Link Relation Type 193 In addition to the Deprecation HTTP header, the server could use a 194 "Link" header(s) to communicate to the client where to find more 195 information about deprecation of the resource in context. This 196 information could be in the form of documentation of the resource 197 including details about the deprecation related aspects of the 198 resource or the deprecation policy of the resource provider or both 199 for example. 201 3.1. Documentation 203 For a URI-identified resource, deprecation could involve one or more 204 parts of request, response or both. These parts could be one or more 205 of the following. 207 o URI - deprecation of one ore more query parameter(s) or path 208 element(s) 210 o method - HTTP method for the resource is deprecated 212 o request header - one or more HTTP request header(s) is deprecated 214 o response header - HTTP response header(s) is deprecated 216 o request body - request body contains one or more deprecated 217 element(s) 219 o response body - response body contains one or more deprecated 220 element(s) 222 The purpose of the "Deprecation" header is to provide just enough 223 "hints" about the deprecation to the client application developer. 224 It is safe to assume that on reception of the "Deprecation" header, 225 the client developer would look up the resource's documentation in 226 order to find deprecation related semantics. The resource developer 227 could provide a link to the resource documentation using a "Link" 228 header with relation type "deprecation" as shown below. 230 Deprecation: version="v1" 231 Link: ; rel="deprecation" 232 type="text/html" 234 where content at "https://developer.example.com/v1/customers" would 235 be annotated to show deprecation of the relevant parts of the 236 "customers" resource. 238 3.2. Policy 240 Resource provider would typically document versioning and deprecation 241 policy with the resource documentation. To inform the client 242 application developer of the deprecation policy, the resource 243 provider could use the "deprecation" relation type as shown below. 245 Deprecation: version="v1" 246 Link: ; rel="deprecation" 247 type="text/html" 249 where deprecation policy of the resource provider "example.com" is 250 described at "https://developer.example.com/deprecation". 252 4. Recommend Replacement 254 "Link" [RFC8288] header could be used in addition to the 255 "Deprecation" header to recommend the client application about 256 available alternates to the deprecated resource. Following relation 257 types as defined in [RFC8288] are RECOMMENDED to use for the purpose. 259 o "successor-version": Points to a resource containing the successor 260 version. [RFC5829] 262 o "latest-version": Points to a resource containing the latest 263 (e.g., current) version. [RFC5829] 265 o "alternate": Designates a substitute. [W3C.REC-html401-19991224] 267 Following example provides link to the successor version of the v1 268 version of "customer" resource that is deprecated. 270 Deprecation: version="v1" 271 Link: ; rel="successor-version" 273 This example provides link to an alternate resource to the "customer" 274 resource that is deprecated. 276 Deprecation: version="2018-11-11" 277 Link: ; rel="alternate" 279 5. Sunset 281 In addition to the deprecation related information, if the resource 282 provider wants to convey to the client application that the 283 deprecated resource is expected to become unresponsive at a specific 284 point in time, the [Sunset] header could be used in addition to the 285 "Deprecation" header. 287 Following example indicates that the resource in context has been 288 deprecated since version v2 and its sunset date is Friday, November 289 11, 2020 at 23:59:59 GMT. 291 Deprecation: version="v2" 292 Sunset: Fri, 11 Nov 2020 23:59:59 GMT 294 Following example shows that the resource in context has been 295 deprecated since Friday, November 11, 2018 at 23:59:59 GMT and its 296 sunset date is Friday, November 11, 2020 at 23:59:59 GMT. 298 Deprecation: date="Fri, 11 Nov 2018 23:59:59 GMT" 299 Sunset: Fri, 11 Nov 2020 23:59:59 GMT 301 6. IANA Considerations 303 6.1. The Deprecation Response Header Field 305 The "Deprecation" response header should be added to the permanent 306 registry of message header fields (see [RFC3864]), taking into 307 account the guidelines given by HTTP/1.1 [RFC7231]. 309 Header Field Name: Deprecation 311 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 313 Status: Standard 315 Author: Sanjay Dalal , 316 Erik Wilde 318 Change controller: IETF 320 Specification document: this specification, 321 Section 2 "The Deprecation HTTP Response Header Field" 323 6.2. The Deprecation Link Relation Type 325 The "deprecation" link relation type should be added to the permanent 326 registry of link relation types according to Section 4.2 of 327 [RFC8288]: 329 Relation Type: deprecation 331 Applicable Protocol: Hypertext Transfer Protocol (HTTP) 333 Status: Standard 335 Author: Sanjay Dalal , 336 Erik Wilde 338 Change controller: IETF 340 Specification document: this specification, 341 Section 3 "The Deprecation Link Relation Type" 343 7. Implementation Status 345 Note to RFC Editor: Please remove this section before publication. 347 This section records the status of known implementations of the 348 protocol defined by this specification at the time of posting of this 349 Internet-Draft, and is based on a proposal described in [RFC7942]. 350 The description of implementations in this section is intended to 351 assist the IETF in its decision processes in progressing drafts to 352 RFCs. Please note that the listing of any individual implementation 353 here does not imply endorsement by the IETF. Furthermore, no effort 354 has been spent to verify the information presented here that was 355 supplied by IETF contributors. This is not intended as, and must not 356 be construed to be, a catalog of available implementations or their 357 features. Readers are advised to note that other implementations may 358 exist. 360 According to RFC 7942, "this will allow reviewers and working groups 361 to assign due consideration to documents that have the benefit of 362 running code, which may serve as evidence of valuable experimentation 363 and feedback that have made the implemented protocols more mature. 364 It is up to the individual working groups to use this information as 365 they see fit". 367 Organization: Zapier 369 Description: Zapier uses two custom HTTP headers named "X-API- 370 Deprecation-Date" and "X-API-Deprecation-Info" 372 Reference: https://zapier.com/engineering/api-geriatrics/ 374 Organization: IBM 376 IBM uses a custom HTTP header named "Deprecated" 377 Reference: 378 https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/ 379 com.ibm.qradar.doc/c_rest_api_getting_started.html 381 Organization: Ultipro 383 Description: Ultipro uses the HTTP "Warning" header as described in 384 Section 5.5 of [RFC7234] with code "299" 386 Reference: https://connect.ultipro.com/api-deprecation 388 Organization: Clearbit 390 Description: Clearbit uses a custom HTTP header named "X-API-Warn" 392 Reference: https://blog.clearbit.com/dealing-with-deprecation/ 394 Organization: PayPal 396 Description: PayPal uses a custom HTTP header named "PayPal- 397 Deprecated" 399 Reference: https://github.com/paypal/api-standards/blob/master/api- 400 style-guide.md#runtime 402 8. Security Considerations 404 The content of a "Link" header field is not secure, private or 405 integrity-guaranteed, and due caution should be exercised when using 406 it. Use of Transport Layer Security (TLS) with HTTP ([RFC7230] is 407 currently the only end-to-end way to provide such protection. 409 The suggested "Link" header fields make extensive use of IRIs and 410 URIs. See [RFC3987] for security considerations relating to IRIs. 411 See [RFC3986] for security considerations relating to URIs. See 412 [RFC7230] for security considerations relating to HTTP headers. 414 Applications that take advantage of typed links should consider the 415 attack vectors opened by automatically following, trusting, or 416 otherwise using links gathered from the HTTP headers. In particular, 417 Link headers that use the "successor-version", "latest-version" or 418 "alternate" relation types should be treated with due caution. See 419 [RFC5829] for security considerations relating to these link relation 420 types. 422 9. Example 424 Just deprecation header without any Link headers. 426 Deprecation: version="v1" 428 Deprecation header with link to the successor version. 430 Deprecation: version="v1" 431 Link: ; rel="successor-version" 433 Deprecation header with links for the successor version and for the 434 API developer's deprecation policy. Also, it shows sunset date for 435 the deprecated version (v1). 437 Deprecation: version="v1" 438 Sunset: Fri, 11 Nov 2020 23:59:59 GMT 439 Link: ; rel="successor-version" 440 Link: ; rel="deprecation" 442 10. References 444 10.1. Normative References 446 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 447 Requirement Levels", BCP 14, RFC 2119, 448 DOI 10.17487/RFC2119, March 1997, 449 . 451 [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration 452 Procedures for Message Header Fields", BCP 90, RFC 3864, 453 DOI 10.17487/RFC3864, September 2004, 454 . 456 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 457 Resource Identifier (URI): Generic Syntax", STD 66, 458 RFC 3986, DOI 10.17487/RFC3986, January 2005, 459 . 461 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 462 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 463 January 2005, . 465 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 466 Specifications: ABNF", STD 68, RFC 5234, 467 DOI 10.17487/RFC5234, January 2008, 468 . 470 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 471 Protocol (HTTP/1.1): Message Syntax and Routing", 472 RFC 7230, DOI 10.17487/RFC7230, June 2014, 473 . 475 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 476 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 477 DOI 10.17487/RFC7231, June 2014, 478 . 480 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 481 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 482 RFC 7234, DOI 10.17487/RFC7234, June 2014, 483 . 485 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 486 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 487 May 2017, . 489 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 490 DOI 10.17487/RFC8288, October 2017, 491 . 493 10.2. Informative References 495 [Deprecation] 496 Marks, S., "JEP 277 - Enhanced Deprecation", 2017, 497 . 499 [RFC5829] Brown, A., Clemm, G., and J. Reschke, Ed., "Link Relation 500 Types for Simple Version Navigation between Web 501 Resources", RFC 5829, DOI 10.17487/RFC5829, April 2010, 502 . 504 [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running 505 Code: The Implementation Status Section", BCP 205, 506 RFC 7942, DOI 10.17487/RFC7942, July 2016, 507 . 509 [Sunset] Wilde, E., "The Sunset HTTP Header Field", 2019, 510 . 513 Appendix A. Acknowledgments 515 The authors would like to thank Mark Nottingham and Nikhil Kolekar 516 for reviewing this specification. 518 The authors take all responsibility for errors and omissions. 520 Authors' Addresses 522 Sanjay Dalal 524 Email: sanjay.dalal@cal.berkeley.edu 525 URI: https://github.com/sdatspun2 527 Erik Wilde 529 Email: erik.wilde@dret.net 530 URI: http://dret.net/netdret