The Deprecation HTTP Header Field
draft-ietf-httpapi-deprecation-header-09

HTTPAPI                                                         S. Dalal
Internet-Draft                                                          
Intended status: Standards Track                                E. Wilde
Expires: 31 March 2025                                 27 September 2024

                   The Deprecation HTTP Header Field
                draft-ietf-httpapi-deprecation-header-09

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 31 March 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.

Table of Contents

   1.  Introduction
     1.1.  Notational Conventions
   2.  The Deprecation HTTP Response Header Field
     2.1.  Syntax
     2.2.  Scope
   3.  The Deprecation Link Relation Type
     3.1.  Documentation
   4.  Sunset
   5.  Resource Behavior
   6.  IANA Considerations
     6.1.  The Deprecation HTTP Response Header Field
     6.2.  The Deprecation Link Relation Type
   7.  Security Considerations
   8.  Normative References
   Appendix A.  Implementation Status
     A.1.  Implementing the Deprecation Header Field
     A.2.  Implementing the Concept
   Appendix B.  Changes from Draft-08
   Appendix C.  Acknowledgments
   Authors' Addresses

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.

3.  The Deprecation Link Relation Type

   In addition to the Deprecation HTTP header field, the server can use
   links with the "deprecation" link relation type to communicate to the
   client application developer where to find more information about
   deprecation of the context.  This can happen before the actual
   deprecation, to make a deprecation policy discoverable, or after
   deprecation, when there may be documentation about the deprecation,
   and possibly documentation of how to manage it.

   This specification places no restrictions on the representation of
   the linked deprecation policy.  In particular, the deprecation policy
   may be available as human-readable documentation or as machine-
   readable description.

3.1.  Documentation

   The purpose of the Deprecation header field is to provide a hint
   about deprecation to the resource consumer.  Upon reception of the
   Deprecation header field, the client application developer can look
   up the resource's documentation in order to find deprecation related
   information.  The documentation MAY provide a guide and timeline to
   migrate away from the deprecated resource to a new resource(s)
   replacing the deprecated resource, if applicable.  The resource
   provider can provide a link to the resource documentation using a
   Link header field with relation type deprecation as shown below:

   Link: <https://developer.example.com/deprecation>;
         rel="deprecation"; type="text/html"

   In this example the linked content provides additional information
   about deprecation of the resource context.  There is no Deprecation
   header field in the response, and thus the resource is not (yet)
   deprecated.  However, the resource already exposes a link where
   information is available describing how deprecation is managed for
   the resource.  This may be the documentation explaining under which
   circumstances and with which policies deprecation might take place.
   For example, a policy may indicate that deprecation of a resource(s)
   will always be signaled in the dedicated places at least N days ahead
   of the planned deprecation date and then only the resource(s) would
   be deprecated.  Or a policy may indicate that resource(s) would be
   deprecated first and then only be signaled as deprecated at dedicated
   places.  The documentation in addition to the deprecation policy may
   also provide a migration guide exaplaining to consumers of the
   resource how to migrate to a new resource(s) or an alternate
   resource(s) before the deprecation date.  Such policy and
   documentation would be very useful to consumers of the resource to
   plan ahead and migrate successfully.

   The following example uses the same link header field, but also
   announces a deprecation date using a Deprecation header field:

   Deprecation: @1688169599
   Link: <https://developer.example.com/deprecation>;
         rel="deprecation"; type="text/html"

   Given that the deprecation date is in the past, the linked
   information resource may have been updated to include information
   about the deprecation, allowing consumers to discover information
   about the deprecation and how to best manage it.

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"

6.2.  The Deprecation Link Relation Type

   The deprecation link relation type should be added to the permanent
   registry of link relation types (Section 4.2 of [LINK]).

Relation Name: deprecation

Description: Refers to a resource that is documentation (intended for human consumption) about the deprecation of the link's context.

Specification document: this specification,
        Section 3 "The Deprecation Link Relation Type"

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/rfc/rfc9110>.

   [LINK]     Nottingham, M., "Web Linking", RFC 8288,
              DOI 10.17487/RFC8288, October 2017,
              <https://www.rfc-editor.org/rfc/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/rfc/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/rfc/rfc8174>.

   [RFC8594]  Wilde, E., "The Sunset HTTP Header Field", RFC 8594,
              DOI 10.17487/RFC8594, May 2019,
              <https://www.rfc-editor.org/rfc/rfc8594>.

   [STRUCTURED-FIELDS]
              Nottingham, M. and P. Kamp, "Structured Field Values for
              HTTP", Work in Progress, Internet-Draft, draft-ietf-
              httpbis-sfbis-06, 21 April 2024,
              <https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
              sfbis-06>.

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:

   *  Addresses comments from Gen-ART, ARTART, SECDIR

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