HTTPAPI Working GroupS. Dalal
Internet-DraftE. Wilde
Intended status: Standards TrackOctober 1, 2024
Expires: April 4, 2025

The Deprecation HTTP Header Field

Abstract

The Deprecation HTTP response header field is used to signal to consumers of a resource (in the sense of URI) that the resource will be or has been deprecated. Additionally, the deprecation link relation can be used to link to a resource that provides additional information about planned or existing deprecation, and possibly ways in which client application developers can best manage deprecation.

About This Document

This note is to be removed before publishing as an RFC.

Status information for this document may be found at <https://datatracker.ietf.org/doc/draft-ietf-httpapi-deprecation-header/>.

Discussion of this document takes place on the HTTPAPI Working Group mailing list (<mailto:httpapi@ietf.org>), which is archived at <https://mailarchive.ietf.org/arch/browse/httpapi/>. Subscribe at <https://www.ietf.org/mailman/listinfo/httpapi/>. Working Group information can be found at <https://ietf-wg-httpapi.github.io/>.

Source for this draft and an issue tracker can be found at <https://github.com/ietf-wg-httpapi/deprecation-header>.

Status of this Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress”.

This Internet-Draft will expire on April 4, 2025.

Copyright Notice

Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.


1. Introduction

Deprecation of an HTTP resource (Section 3.1 of [HTTP]) communicates information about the lifecycle of a resource. It encourages client applications to migrate away from the resource, discourages applications from forming new dependencies on the resource, and informs applications about the risk of continued dependence upon the resource.

The act of deprecation does not change any behavior of the resource. It informs client applications of the fact that a resource will be or is deprecated. The Deprecation HTTP response header field can be used to convey this information at runtime indicating when the deprecation will be in effect.

In addition to the Deprecation header field, the resource provider can use other header fields such as Link ([LINK]) to convey additional information related to deprecation. This can be information such as where to find documentation related to the deprecation, what can be used as a replacement, and when a deprecated resource becomes non-operational.

1.1. Notational Conventions

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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

This document uses "Structured Field Values for HTTP" ([STRUCTURED-FIELDS]) to specify syntax and parsing of date values.

The term "resource" is to be interpreted as defined in Section 3.1 of [HTTP].

2. The Deprecation HTTP Response Header Field

The Deprecation HTTP response header field allows a server to communicate to a client application that the resource in context of the message is or will be deprecated.

2.1. Syntax

The Deprecation response header field describes the deprecation of the resource identified with the response it occurred within (see Section 6.4.2 of [HTTP]). It conveys the deprecation date, which may be in the future (the resource context will be deprecated at that date) or in the past (the resource context has been deprecated at that date).

Deprecation is an Item Structured Header Field; its value MUST be a Date as per Section 3.3.7 of [STRUCTURED-FIELDS].

The following example shows that the resource context has been deprecated on Friday, June 30, 2023 at 23:59:59 UTC:

Deprecation: @1688169599

2.2. Scope

The Deprecation header field applies to the resource identified with the response it occurred within (see Section 6.4.2 of [HTTP]), meaning that it announces the upcoming deprecation of that specific resource. However, there may be scenarios where the scope of the announced deprecation is larger than just the single resource where it appears.

Resources are free to define such an increased scope, and usually this scope will be documented by the resource so that consumers of the resource know about the increased scope and can behave accordingly. When doing so, it is important to take into account that such increased scoping is invisible for consumers who are unaware of the increased scoping rules. This means that these consumers will not be aware of the increased scope, and they will not interpret deprecation information different from its standard meaning (i.e., it applies to the resource only).

Using such an increased scope still may make sense, as deprecation information is only a hint anyway. It is optional information that cannot be depended on, and client applications should always be implemented in ways that allow them to function without Deprecation information. Increased scope information may help client application developers to glean additional hints from related resources and, thus, might allow them to implement behavior that allows them to make educated guesses about resources becoming deprecated.

For example, an API might not use Deprecation header fields on all of its resources, but only on designated resources such as the API's home document. This means that deprecation information is available, but in order to get it, client application developers have to periodically inspect the home document. In this example, the extended context of the Deprecation header field would be all resources provided by the API, while the visibility of the information would only be on the home document.

4. Sunset

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 Sunset HTTP header field [RFC8594] can be used in addition to the Deprecation header field.

The timestamp given in the Sunset header field MUST NOT be earlier than the one given in the Deprecation header field. If that happens for some reasons such as misconfiguration of deployment of the resource or an error, the client application developer SHOULD consult the resource developer to get clarification.

The following example shows that the resource in context has been deprecated since Friday, June 30, 2023 at 23:59:59 UTC and its sunset date is Sunday, June 30, 2024 at 23:59:59 UTC. Please note that for historical reasons the Sunset HTTP header field uses a different data format for date.

Deprecation: @1688169599
Sunset: Sun, 30 Jun 2024 23:59:59 UTC

5. Resource Behavior

The act of deprecation does not change any behavior of the resource. The presence of a Deprecation header field in response is not meant to signal a change in the meaning or function of a resource in the context, allowing consumers to still use the resource in the same way as they did before the resource was declared deprecated.

6. IANA Considerations

6.1. The Deprecation HTTP Response Header Field

The Deprecation response header field should be added to the "Hypertext Transfer Protocol (HTTP) Field Name Registry" registry (Section 16.3.1 of [HTTP])

Header Field Name: Deprecation

Structured Type: Item

Status: permanent

Specification document: this specification,
            Section 2 "The Deprecation HTTP Response Header Field"

7. Security Considerations

The Deprecation header field should be treated as a hint, meaning that the resource is indicating (and not guaranteeing with certainty) that it will be or is deprecated. Deprecated resources function as they would have without sending the deprecation header field, even though one might consider non-functional details such as making them progressively less efficient with longer response time for example.

Resource documentation should provide additional information about the deprecation, such as including recommendation(s) for replacement. Developers of client applications consuming the resource SHOULD always check the referred resource documentation to verify authenticity and accuracy. In cases where a Link header field is used to provide documentation, one should assume (unless served over HTTPS) that the content of the Link header field may not be secure, private or integrity-guaranteed, and due caution should be exercised when using it, see Section 5 of [LINK] for more details. In cases where the Deprecation header field value is in the past, the client application developers MUST no longer assume that the behavior of the resource would remain the same as before the deprecation date. In cases where the Deprecation header field value is a date in the future, it can lead to information that otherwise might not be available. Therefore, client application developers consuming the resource SHOULD, if possible, consult the resource developer to discuss potential impact due to deprecation and plan for possible transition to a recommended resource(s).

8. Normative References

[HTTP]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., “HTTP Semantics”, STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/info/rfc9110>.
Nottingham, M., “Web Linking”, RFC 8288, DOI 10.17487/RFC8288, October 2017, <https://www.rfc-editor.org/info/rfc8288>.
[RFC2119]
Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”, BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174]
Leiba, B., “Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words”, BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8594]
Wilde, E., “The Sunset HTTP Header Field”, RFC 8594, DOI 10.17487/RFC8594, May 2019, <https://www.rfc-editor.org/info/rfc8594>.
[STRUCTURED-FIELDS]
Nottingham, M. and P. Kamp, “Structured Field Values for HTTP”, Internet-Draft draft-ietf-httpbis-sfbis-06 (work in progress), April 2024.

Appendix A. Implementation Status

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. 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".

A.1. Implementing the Deprecation Header Field

This is a list of implementations that implement the deprecation header field:

Organization: Apollo

  • Description: Deprecation header field is returned when deprecated functionality (as declared in the GraphQL schema) is accessed
  • Reference: https://www.npmjs.com/package/apollo-server-tools

Organization: Zalando

  • Description: Deprecation header field is recommended as the preferred way to communicate API deprecation in Zalando API designs.
  • Reference: https://opensource.zalando.com/restful-api-guidelines/#deprecation

Organization: Palantir Technologies

  • Description: Deprecation header field is incorporated in code generated by conjure-java, a CLI to generate Java POJOs and interfaces from Conjure API definitions
  • Reference: https://github.com/palantir/conjure-java

Organization: E-Voyageurs Technologies

  • Description: Deprecation header field is incorporated in Hesperides, a configuration management tool providing universal text file templating and properties editing through a REST API or a webapp.
  • Reference: https://github.com/voyages-sncf-technologies/hesperides/blob/master/documentation/lightweight-architecture-decision-records/deprecated_endpoints.md

Organization: Open-Xchange

  • Description: Deprecation header field is used in Open-Xchange appsuite-middleware
  • Reference: https://github.com/open-xchange/appsuite-middleware

Organization: MediaWiki

  • Description: Core REST API of MediaWiki would use Deprecation header field for endpoints that have been deprecated because a new endpoint provides the same or better functionality.
  • Reference: https://phabricator.wikimedia.org/T232485

In addition to the above list, the Deprecation link relation is returned in the Registration Data Access Protocol (RDAP) notices to indicate deprecation of jCard in favor of JSContact. RDAP is specified in the Internet Draft for Using JSContact in Registration Data Access Protocol (RDAP) JSON Responses https://datatracker.ietf.org/doc/draft-ietf-regext-rdap-jscontact/.

A.2. Implementing the Concept

This is a list of implementations that implement the general concept, but do so using different mechanisms:

Organization: Zapier

  • Description: Zapier uses two custom HTTP header fields named X-API-Deprecation-Date and X-API-Deprecation-Info
  • Reference: https://zapier.com/engineering/api-geriatrics/

Organization: IBM

  • Description: IBM uses a custom HTTP header field named Deprecated
  • Reference: https://www.ibm.com/support/knowledgecenter/en/SS42VS_7.3.1/com.ibm.qradar.doc/c_rest_api_getting_started.html

Organization: Ultipro

  • Description: Ultipro uses the HTTP Warning header field as described in Section 5.5 of RFC 9111 with code 299
  • Reference: https://connect.ultipro.com/api-deprecation

Organization: Clearbit

  • Description: Clearbit uses a custom HTTP header field named X-API-Warn
  • Reference: https://blog.clearbit.com/dealing-with-deprecation/

Organization: PayPal

  • Description: PayPal uses a custom HTTP header field named PayPal-Deprecated
  • Reference: https://github.com/paypal/api-standards/blob/master/api-style-guide.md#runtime

Appendix B. Changes from Draft-08

This revision has made the following changes:

Appendix C. Acknowledgments

The authors would like to thank Nikhil Kolekar, Darrel Miller, Mark Nottingham, and Roberto Polli for their contributions.

The authors take all responsibility for errors and omissions.

Authors' Addresses

Sanjay Dalal
EMail: sanjay.dalal@cal.berkeley.edu
URI: https://github.com/sdatspun2
Erik Wilde
EMail: erik.wilde@dret.net
URI: http://dret.net/netdret