The Deprecation HTTP Headersanjay.dalal@cal.berkeley.eduhttps://github.com/sdatspun2erik.wilde@dret.nethttp://dret.net/netdretThe HTTP Deprecation response header can be used to signal to consumers of a URI-identified resource that the use of the resource has been deprecated. Additionally, the deprecation link relation can be used to link to a resource that provides additional context for the deprecation, and possibly ways in which clients can find a replacement for the deprecated resource.Deprecation of a URI-identified resource is a technique to communicate information about the lifecycle of a resource. It encourages applications to migrate away from the resource and discourage applications from forming new dependencies on the resource, and informs applications of the risk of continuing dependence upon the resource.The act of deprecation does not change any behavior of the resource. It just informs client of the fact that a resource is deprecated. The Deprecation HTTP response header field MAY be used to convey this fact at runtime to clients. The header field can carry additional information such as since when the deprecation is in effect.In addition to the Deprecation header field the resource provider can use other header fields to convey additional information related to deprecation. For example, information such as where to find documentation related to the deprecation or what should be used as an alternate and when the deprecated resource would be unreachable, etc. Alternates of a resource can be similar resource(s) or a newer version of the same resource.The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.This specification uses the Augmented Backus-Naur Form (ABNF) notation of and includes, by reference, the “token” rule, DQUOTE (double quote) rule, the SP (space) rule and the “rule” extension that allows for compact definition of comma-separated lists using a ‘#’ operator (similar to how the ‘*’ operator indicates repetition), HTTP-date rule as defined within Sections 3.2.6 and 7 of and Section 7.1.1 of .The Deprecation HTTP response header field allows a server to communicate to a client that the URI-identified resource in context of the message is deprecated. It can also provide information that the resource is deprecated since which version.The Deprecation response header contains the header name “Deprecation” followed by a “:” and a property(s). Each property consists of a name-value-pair. Servers SHOULD NOT send Deprecation headers that fail to conform to the following grammar:Note that some of the grammatical terms above reference documents that use different grammatical notations than this document (which uses ABNF from ).Servers SHOULD NOT include more than one Deprecation header field in the same response. If a server sends multiple responses containing Deprecation headers concurrently to the user agent (e.g., when communicating with the user agent over multiple sockets), these responses create a “race condition” that can lead to unpredictable behavior.The value of Deprecation response header field could consist of at least 1 standard property: date or version as shown below. Either of version or date is REQUIRED and both are also allowed.The value of the version property, if present, could be the version of the resource that is deprecated. The value of version would be an opaque version identifier. For resources that use date-based versioning scheme, the value would be accordingly.Following example indicates that the version v1 of the resource in context is deprecated.Following example shows that the version 2018-11-08 (November 8, 2018) of the resource in context is deprecated. Here the versioning scheme used is date-based.The value of date property, if present, would be the date when resource was deprecated. It would be in the form of a quoted HTTP-date timestamp, as defined in Section 7.1.1.1 of .Following example shows that the resource in context is deprecated on Friday, November 11, 2018 at 23:59:59 GMT.Date could be in future too. If the value of date is in future, it means that the resource would be deprecated on the given date in future.In addition to the Deprecation HTTP header, the server could use a Link header(s) to communicate to the client where to find more information about deprecation of the resource in context. This information could be in the form of documentation of the resource including details about the deprecation related aspects of the resource or the deprecation policy of the resource provider or both for example.For a URI-identified resource, deprecation could involve one or more parts of request, response or both. These parts could be one or more of the following.URI - deprecation of one ore more query parameter(s) or path element(s)method - HTTP method for the resource is deprecatedrequest header - one or more HTTP request header(s) is deprecatedresponse header - HTTP response header(s) is deprecatedrequest body - request body contains one or more deprecated element(s)response body - response body contains one or more deprecated element(s)The purpose of the Deprecation header is to provide just enough “hints” about the deprecation to the client application developer. It is safe to assume that on reception of the Deprecation header, the client developer would look up the resource’s documentation in order to find deprecation related semantics. The resource developer could provide a link to the resource documentation using a Link header with relation type deprecation as shown below.where content at https://developer.example.com/v1/customers would be annotated to show deprecation of the relevant parts of the customers resource.Resource provider would typically document versioning and deprecation policy with the resource documentation. To inform the client application developer of the deprecation policy, the resource provider could use the deprecation relation type as shown below.where deprecation policy of the resource provider example.com is described at https://developer.example.com/deprecation.Link header could be used in addition to the Deprecation header to recommend the client application about available alternates to the deprecated resource. Following relation types as defined in are RECOMMENDED to use for the purpose.successor-version: Points to a resource containing the successor version. latest-version: Points to a resource containing the latest (e.g., current) version. alternate: Designates a substitute. [W3C.REC-html401-19991224]Following example provides link to the successor version of the v1 version of customer resource that is deprecated.This example provides link to an alternate resource to the customer resource that is deprecated.In addition to the deprecation related information, if the resource provider wants to convey to the client application that the deprecated resource is expected to become unresponsive at a specific point in time, the header could be used in addition to the Deprecation header.Following example indicates that the resource in context has been deprecated since version v2 and its sunset date is Friday, November 11, 2020 at 23:59:59 GMT.Following example shows that the resource in context has been deprecated since Friday, November 11, 2018 at 23:59:59 GMT and its sunset date is Friday, November 11, 2020 at 23:59:59 GMT.The Deprecation response header should be added to the permanent registry of message header fields (see ), taking into account the guidelines given by HTTP/1.1 .The deprecation link relation type should be added to the permanent registry of link relation types according to Section 4.2 of :Note to RFC Editor: Please remove this section before publication.This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in . The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that
other implementations may exist.According to RFC 7942, “this will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature. It is up to the individual working groups to use this information as they see fit”.Organization: ZapierDescription: Zapier uses two custom HTTP headers named X-API-Deprecation-Date and X-API-Deprecation-InfoReference: https://zapier.com/engineering/api-geriatrics/Organization: IBMIBM uses a custom HTTP header named DeprecatedReference: https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/com.ibm.qradar.doc/c_rest_api_getting_started.htmlOrganization: UltiproDescription: Ultipro uses the HTTP Warning header as described in Section 5.5 of with code 299Reference: https://connect.ultipro.com/api-deprecationOrganization: ClearbitDescription: Clearbit uses a custom HTTP header named X-API-WarnReference: https://blog.clearbit.com/dealing-with-deprecation/Organization: PayPalDescription: PayPal uses a custom HTTP header named PayPal-DeprecatedReference: https://github.com/paypal/api-standards/blob/master/api-style-guide.md#runtimeThe content of a Link header field is not secure, private or integrity-guaranteed, and due caution should be exercised when using it. Use of Transport Layer Security (TLS) with HTTP ( is currently the only end-to-end way to provide such protection.The suggested Link header fields make extensive use of IRIs and URIs. See for security considerations relating to IRIs. See for security considerations relating to URIs. See for security considerations relating to HTTP headers.Applications that take advantage of typed links should consider the attack vectors opened by automatically following, trusting, or otherwise using links gathered from the HTTP headers. In particular, Link headers that use the successor-version, latest-version or alternate relation types should be treated with due caution. See for security considerations relating to these link relation types.Just deprecation header without any Link headers.Deprecation header with link to the successor version.Deprecation header with links for the successor version and for the API developer’s deprecation policy. Also, it shows sunset date for the deprecated version (v1).Key words for use in RFCs to Indicate Requirement LevelsIn many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Ambiguity of Uppercase vs Lowercase in RFC 2119 Key WordsRFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings.Augmented BNF for Syntax Specifications: ABNFInternet technical specifications often need to define a formal syntax. Over the years, a modified version of Backus-Naur Form (BNF), called Augmented BNF (ABNF), has been popular among many Internet specifications. The current specification documents ABNF. It balances compactness and simplicity with reasonable representational power. The differences between standard BNF and ABNF involve naming rules, repetition, alternatives, order-independence, and value ranges. This specification also supplies additional rule definitions and encoding for a core lexical analyzer of the type common to several Internet specifications. [STANDARDS-TRACK]Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and RoutingThe Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document provides an overview of HTTP architecture and its associated terminology, defines the "http" and "https" Uniform Resource Identifier (URI) schemes, defines the HTTP/1.1 message syntax and parsing requirements, and describes related security concerns for implementations.Hypertext Transfer Protocol (HTTP/1.1): Semantics and ContentThe Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation.Web LinkingThis specification defines a model for the relationships between resources on the Web ("links") and the type of those relationships ("link relation types").It also defines the serialisation of such links in HTTP headers with the Link header field.Registration Procedures for Message Header FieldsThis specification defines registration procedures for the message header fields used by Internet mail, HTTP, Netnews and other applications. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements.Hypertext Transfer Protocol (HTTP/1.1): CachingThe Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines HTTP caches and the associated header fields that control cache behavior or indicate cacheable response messages.Internationalized Resource Identifiers (IRIs)This document defines a new protocol element, the Internationalized Resource Identifier (IRI), as a complement of the Uniform Resource Identifier (URI). An IRI is a sequence of characters from the Universal Character Set (Unicode/ISO 10646). A mapping from IRIs to URIs is defined, which means that IRIs can be used instead of URIs, where appropriate, to identify resources. The approach of defining a new protocol element was chosen instead of extending or changing the definition of URIs. This was done in order to allow a clear distinction and to avoid incompatibilities with existing software. Guidelines are provided for the use and deployment of IRIs in various protocols, formats, and software components that currently deal with URIs.Uniform Resource Identifier (URI): Generic SyntaxA Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK]JEP 277 - Enhanced DeprecationThe Sunset HTTP Header FieldLink Relation Types for Simple Version Navigation between Web ResourcesThis specification defines a set of link relation types that may be used on Web resources for navigation between a resource and other resources related to version control, such as past versions and working copies. This document is not an Internet Standards Track specification; it is published for informational purposes.Improving Awareness of Running Code: The Implementation Status SectionThis document describes a simple process that allows authors of Internet-Drafts to record the status of known implementations by including an Implementation Status section. This will allow reviewers and working groups to assign due consideration to documents that have the benefit of running code, which may serve as evidence of valuable experimentation and feedback that have made the implemented protocols more mature.This process is not mandatory. Authors of Internet-Drafts are encouraged to consider using the process for their documents, and working groups are invited to think about applying the process to all of their protocol specifications. This document obsoletes RFC 6982, advancing it to a Best Current Practice.The authors would like to thank Mark Nottingham and Nikhil Kolekar for reviewing this specification.The authors take all responsibility for errors and omissions.