rfc9745.original   rfc9745.txt 
HTTPAPI S. Dalal Internet Engineering Task Force (IETF) S. Dalal
Internet-Draft Request for Comments: 9745
Intended status: Standards Track E. Wilde Category: Standards Track E. Wilde
Expires: 31 March 2025 27 September 2024 ISSN: 2070-1721 March 2025
The Deprecation HTTP Header Field The Deprecation HTTP Response Header Field
draft-ietf-httpapi-deprecation-header-09
Abstract Abstract
The Deprecation HTTP response header field is used to signal to The Deprecation HTTP response header field is used to signal to
consumers of a resource (in the sense of URI) that the resource will consumers of a resource (identified by a URI) that the resource will
be or has been deprecated. Additionally, the deprecation link be or has been deprecated. Additionally, the deprecation link
relation can be used to link to a resource that provides additional relation can be used to link to a resource that provides further
information about planned or existing deprecation, and possibly ways information about planned or existing deprecation. It may also
in which client application developers can best manage deprecation. provide 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 Status of This Memo
This Internet-Draft is submitted in full conformance with the This is an Internet Standards Track document.
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 This document is a product of the Internet Engineering Task Force
and may be updated, replaced, or obsoleted by other documents at any (IETF). It represents the consensus of the IETF community. It has
time. It is inappropriate to use Internet-Drafts as reference received public review and has been approved for publication by the
material or to cite them other than as "work in progress." Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of RFC 7841.
This Internet-Draft will expire on 31 March 2025. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc9745.
Copyright Notice Copyright Notice
Copyright (c) 2024 IETF Trust and the persons identified as the Copyright (c) 2025 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/ Provisions Relating to IETF Documents
license-info) in effect on the date of publication of this document. (https://trustee.ietf.org/license-info) in effect on the date of
Please review these documents carefully, as they describe your rights publication of this document. Please review these documents
and restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Revised BSD License text as to this document. Code Components extracted from this document must
described in Section 4.e of the Trust Legal Provisions and are include Revised BSD License text as described in Section 4.e of the
provided without warranty as described in the Revised BSD License. Trust Legal Provisions and are provided without warranty as described
in the Revised BSD License.
Table of Contents Table of Contents
1. Introduction 1. Introduction
1.1. Notational Conventions 1.1. Notational Conventions
2. The Deprecation HTTP Response Header Field 2. The Deprecation HTTP Response Header Field
2.1. Syntax 2.1. Syntax
2.2. Scope 2.2. Scope
3. The Deprecation Link Relation Type 3. The Deprecation Link Relation Type
3.1. Documentation 3.1. Documentation
4. Sunset 4. Sunset
5. Resource Behavior 5. Resource Behavior
6. IANA Considerations 6. IANA Considerations
6.1. The Deprecation HTTP Response Header Field 6.1. The Deprecation HTTP Response Header Field
6.2. The Deprecation Link Relation Type 6.2. The Deprecation Link Relation Type
7. Security Considerations 7. Security Considerations
8. Normative References 8. Normative References
Appendix A. Implementation Status Acknowledgments
A.1. Implementing the Deprecation Header Field
A.2. Implementing the Concept
Appendix B. Changes from Draft-08
Appendix C. Acknowledgments
Authors' Addresses Authors' Addresses
1. Introduction 1. Introduction
Deprecation of an HTTP resource (Section 3.1 of [HTTP]) communicates Deprecation of an HTTP resource (Section 3.1 of [HTTP]) communicates
information about the lifecycle of a resource. It encourages client information about the lifecycle of a resource. It encourages client
applications to migrate away from the resource, discourages applications to migrate away from the resource, discourages
applications from forming new dependencies on the resource, and applications from forming new dependencies on the resource, and
informs applications about the risk of continued dependence upon the informs applications about the risk of continued dependence upon the
resource. resource.
The act of deprecation does not change any behavior of 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 It informs client applications of the fact that a resource will be or
is deprecated. The Deprecation HTTP response header field can be has been deprecated. The Deprecation HTTP response header field can
used to convey this information at runtime indicating when the be used to convey this information at runtime and indicate when the
deprecation will be in effect. deprecation will be in effect.
In addition to the Deprecation header field, the resource provider In addition to the Deprecation header field, the resource provider
can use other header fields such as Link ([LINK]) to convey can use other header fields such as the Link header field [LINK] to
additional information related to deprecation. This can be convey additional information related to deprecation. This can be
information such as where to find documentation related to the information such as where to find documentation related to the
deprecation, what can be used as a replacement, and when a deprecated deprecation, what can be used as a replacement, and when a deprecated
resource becomes non-operational. resource becomes non-operational.
1.1. Notational Conventions 1.1. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in "OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This document uses "Structured Field Values for HTTP" This document uses "Structured Field Values for HTTP" [RFC9651] to
([STRUCTURED-FIELDS]) to specify syntax and parsing of date values. specify syntax and parsing of date values.
The term "resource" is to be interpreted as defined in Section 3.1 of The term "resource" is to be interpreted as defined in Section 3.1 of
[HTTP]. [HTTP].
2. The Deprecation HTTP Response Header Field 2. The Deprecation HTTP Response Header Field
The Deprecation HTTP response header field allows a server to The Deprecation HTTP response header field allows a server to
communicate to a client application that the resource in context of communicate to a client application that the resource in the context
the message is or will be deprecated. of the message will be or has been deprecated.
2.1. Syntax 2.1. Syntax
The Deprecation response header field describes the deprecation of The Deprecation HTTP response header field describes the deprecation
the resource identified with the response it occurred within (see of the resource identified with the response it occurred within (see
Section 6.4.2 of [HTTP]). It conveys the deprecation date, which may 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 be in the future (the resource in context will be deprecated at that
date) or in the past (the resource context has been deprecated at date) or in the past (the resource in context was deprecated at that
that date). date).
Deprecation is an Item Structured Header Field; its value MUST be a Deprecation is an Item Structured Header Field; its value MUST be a
Date as per Section 3.3.7 of [STRUCTURED-FIELDS]. Date as per Section 3.3.7 of [RFC9651].
The following example shows that the resource context has been The following example shows that the resource in context was
deprecated on Friday, June 30, 2023 at 23:59:59 UTC: deprecated on Friday, June 30, 2023 at 23:59:59 UTC:
Deprecation: @1688169599 Deprecation: @1688169599
2.2. Scope 2.2. Scope
The Deprecation header field applies to the resource identified with The Deprecation header field applies to the resource identified with
the response it occurred within (see Section 6.4.2 of [HTTP]), the response it occurred within (see Section 6.4.2 of [HTTP]),
meaning that it announces the upcoming deprecation of that specific meaning that it announces the upcoming deprecation of that specific
resource. However, there may be scenarios where the scope of the resource. However, there may be scenarios where the scope of the
announced deprecation is larger than just the single resource where announced deprecation is larger than just the single resource where
it appears. it appears.
Resources are free to define such an increased scope, and usually Resources are free to define such an increased scope, and usually
this scope will be documented by the resource so that consumers of this scope will be documented by the resource so that consumers of
the resource know about the increased scope and can behave the resource know about the increased scope and can behave
accordingly. When doing so, it is important to take into account accordingly. When doing so, it is important to take into account
that such increased scoping is invisible for consumers who are that such increased scoping is invisible for consumers who are
unaware of the increased scoping rules. This means that these unaware of the increased scoping rules. This means that these
consumers will not be aware of the increased scope, and they will not consumers will not be aware of the increased scope, and they will not
interpret deprecation information different from its standard meaning interpret deprecation-related information differently from its
(i.e., it applies to the resource only). standard meaning (i.e., it applies to the resource only).
Using such an increased scope still may make sense, as deprecation Using such an increased scope still may make sense, as deprecation-
information is only a hint anyway. It is optional information that related information is only a hint anyway. It is optional
cannot be depended on, and client applications should always be information that cannot be depended on, and client applications
implemented in ways that allow them to function without Deprecation should always be implemented in ways that allow them to function
information. Increased scope information may help client application without deprecation-related information. Increased scope information
developers to glean additional hints from related resources and, may help client application developers to glean additional hints from
thus, might allow them to implement behavior that allows them to make related resources and thus might allow them to implement behavior
educated guesses about resources becoming deprecated. that enables them to make educated guesses about resources becoming
deprecated.
For example, an API might not use Deprecation header fields on all of 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 its resources but only on designated resources such as the API's home
home document. This means that deprecation information is available, document. This means that deprecation-related information is
but in order to get it, client application developers have to available, but in order to get it, client application developers have
periodically inspect the home document. In this example, the to periodically inspect the home document. In this example, the
extended context of the Deprecation header field would be all extended context of the Deprecation header field would be all
resources provided by the API, while the visibility of the resources provided by the API, while the visibility of the
information would only be on the home document. information would only be on the home document.
3. The Deprecation Link Relation Type 3. The Deprecation Link Relation Type
In addition to the Deprecation HTTP header field, the server can use In addition to the Deprecation HTTP response header field, the server
links with the "deprecation" link relation type to communicate to the can use links with the deprecation link relation type to communicate
client application developer where to find more information about to the client application developer where to find more information
deprecation of the context. This can happen before the actual about deprecation of the context. This can happen before the actual
deprecation, to make a deprecation policy discoverable, or after deprecation to make a deprecation policy discoverable or after
deprecation, when there may be documentation about the deprecation, deprecation when there may be documentation about the deprecation and
and possibly documentation of how to manage it. how to manage it.
This specification places no restrictions on the representation of This specification places no restrictions on the representation of
the linked deprecation policy. In particular, the deprecation policy the linked deprecation policy. In particular, the deprecation policy
may be available as human-readable documentation or as machine- may be available as human-readable documentation or as a machine-
readable description. readable description.
3.1. Documentation 3.1. Documentation
The purpose of the Deprecation header field is to provide a hint The purpose of the Deprecation header field is to provide a hint
about deprecation to the resource consumer. Upon reception of the about deprecation to the resource consumer. Upon reception of the
Deprecation header field, the client application developer can look Deprecation header field, the client application developer can look
up the resource's documentation in order to find deprecation related up the resource's documentation in order to find deprecation-related
information. The documentation MAY provide a guide and timeline to information. The documentation MAY provide a guide and timeline for
migrate away from the deprecated resource to a new resource(s) migrating away from the deprecated resource to a new resource(s) that
replacing the deprecated resource, if applicable. The resource replaces the deprecated resource, if applicable. The resource
provider can provide a link to the resource documentation using a provider can provide a link to the resource's documentation using a
Link header field with relation type deprecation as shown below: Link header field with the relation type deprecation as shown below:
Link: <https://developer.example.com/deprecation>; Link: <https://developer.example.com/deprecation>;
rel="deprecation"; type="text/html" rel="deprecation"; type="text/html"
In this example the linked content provides additional information In this example, the linked content provides additional information
about deprecation of the resource context. There is no Deprecation about deprecation of the resource in context. There is no
header field in the response, and thus the resource is not (yet) Deprecation header field in the response; thus, the resource is not
deprecated. However, the resource already exposes a link where (yet) deprecated. However, the resource already exposes a link where
information is available describing how deprecation is managed for information describing how deprecation is managed for the resource is
the resource. This may be the documentation explaining under which available. This may be the documentation explaining the
circumstances and with which policies deprecation might take place. circumstances in which deprecation might take place and the
For example, a policy may indicate that deprecation of a resource(s) deprecation policies. For example, a policy may indicate that
will always be signaled in the dedicated places at least N days ahead deprecation of a resource(s) will always be signaled in the dedicated
of the planned deprecation date and then only the resource(s) would places at least N days ahead of the planned deprecation date and then
be deprecated. Or a policy may indicate that resource(s) would be the resource(s) would be deprecated on the planned date. Or a policy
deprecated first and then only be signaled as deprecated at dedicated may indicate that the resource(s) would be deprecated first and then
places. The documentation in addition to the deprecation policy may be signaled as deprecated at dedicated places. The documentation, in
also provide a migration guide exaplaining to consumers of the addition to the deprecation policy, may also provide a migration
resource how to migrate to a new resource(s) or an alternate guide explaining to consumers of the resource how to migrate to a new
resource(s) before the deprecation date. Such policy and or alternate resource(s) before the deprecation date. Such policy
documentation would be very useful to consumers of the resource to and documentation would be very useful to consumers of the resource
plan ahead and migrate successfully. to plan ahead and migrate successfully.
The following example uses the same link header field, but also The following example uses the same Link header field but also
announces a deprecation date using a Deprecation header field: announces a deprecation date using a Deprecation header field:
Deprecation: @1688169599 Deprecation: @1688169599
Link: <https://developer.example.com/deprecation>; Link: <https://developer.example.com/deprecation>;
rel="deprecation"; type="text/html" rel="deprecation"; type="text/html"
Given that the deprecation date is in the past, the linked Given that the deprecation date is in the past, the linked
information resource may have been updated to include information information resource may have been updated to include information
about the deprecation, allowing consumers to discover information about the deprecation, allowing consumers to discover information
about the deprecation and how to best manage it. about the deprecation and how to best manage it.
4. Sunset 4. Sunset
In addition to the deprecation related information, if the resource In addition to the deprecation-related information, if the resource
provider wants to convey to the client application that the provider wants to convey to the client application that the
deprecated resource is expected to become unresponsive at a specific deprecated resource is expected to become unresponsive at a specific
point in time, the Sunset HTTP header field [RFC8594] can be used in point in time, the Sunset HTTP header field [RFC8594] can be used in
addition to the Deprecation header field. addition to the Deprecation header field.
The timestamp given in the Sunset header field MUST NOT be earlier The timestamp given in the Sunset HTTP header field MUST NOT be
than the one given in the Deprecation header field. If that happens earlier than the one given in the Deprecation header field. If that
for some reasons such as misconfiguration of deployment of the happens (for example, due to misconfiguration of deployment of the
resource or an error, the client application developer SHOULD consult resource or an error), the client application developer SHOULD
the resource developer to get clarification. consult the resource developer to get clarification.
The following example shows that the resource in context has been The following example shows that the resource in context was
deprecated since Friday, June 30, 2023 at 23:59:59 UTC and its sunset deprecated on 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 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 historical reasons the Sunset HTTP header field uses a different data
format for date. format for date.
Deprecation: @1688169599 Deprecation: @1688169599
Sunset: Sun, 30 Jun 2024 23:59:59 UTC Sunset: Sun, 30 Jun 2024 23:59:59 UTC
5. Resource Behavior 5. Resource Behavior
The act of deprecation does not change any behavior of the resource. The act of deprecation does not change any behavior of the resource.
The presence of a Deprecation header field in response is not meant The presence of a Deprecation header field in a response is not meant
to signal a change in the meaning or function of a resource in the 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 context; consumers can still use the resource in the same way as they
as they did before the resource was declared deprecated. did before the resource was declared deprecated.
6. IANA Considerations 6. IANA Considerations
6.1. The Deprecation HTTP Response Header Field 6.1. The Deprecation HTTP Response Header Field
The Deprecation response header field should be added to the The Deprecation HTTP response header field has been added to the
"Hypertext Transfer Protocol (HTTP) Field Name Registry" registry "Hypertext Transfer Protocol (HTTP) Field Name Registry"
(Section 16.3.1 of [HTTP]) (Section 16.3.1 of [HTTP]) as follows:
Header Field Name: Deprecation Field Name: Deprecation
Structured Type: Item Status: permanent
Status: permanent Structured Type: Item
Specification document: this specification, Reference: RFC 9745, Section 2: The Deprecation HTTP Response Header
Section 2 "The Deprecation HTTP Response Header Field" Field
6.2. The Deprecation Link Relation Type 6.2. The Deprecation Link Relation Type
The deprecation link relation type should be added to the permanent The deprecation link relation type has been added to the "Link
registry of link relation types (Section 4.2 of [LINK]). Relation Types" registry (Section 4.2 of [LINK]) as follows:
Relation Name: deprecation Relation Name: deprecation
Description: Refers to a resource that is documentation (intended for human consumption) about the deprecation of the link's context. Description: Refers to documentation (intended for human
consumption) about the deprecation of the link's context.
Specification document: this specification, Reference: RFC 9745, Section 3
Section 3 "The Deprecation Link Relation Type"
7. Security Considerations 7. Security Considerations
The Deprecation header field should be treated as a hint, meaning The Deprecation header field should be treated as a hint, meaning
that the resource is indicating (and not guaranteeing with certainty) that the resource is indicating (but not guaranteeing with certainty)
that it will be or is deprecated. Deprecated resources function as that it will be or has been deprecated. Deprecated resources
they would have without sending the deprecation header field, even function as they would have without sending the Deprecation header
though one might consider non-functional details such as making them field, even though non-functional details may be affected (e.g., they
progressively less efficient with longer response time for example. have less efficiency and longer response times).
Resource documentation should provide additional information about The resource's documentation should provide additional information
the deprecation, such as including recommendation(s) for replacement. about the deprecation, such as recommendations for replacement.
Developers of client applications consuming the resource SHOULD Developers of client applications consuming the resource SHOULD
always check the referred resource documentation to verify always check the referred resource's documentation to verify
authenticity and accuracy. In cases where a Link header field is authenticity and accuracy. In cases where a Link header field is
used to provide documentation, one should assume (unless served over used to provide documentation, one should assume (unless served over
HTTPS) that the content of the Link header field may not be secure, HTTPS) that the content of the Link header field may not be secure,
private or integrity-guaranteed, and due caution should be exercised private, or integrity-guaranteed, so due caution should be exercised
when using it, see Section 5 of [LINK] for more details. In cases 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 where the Deprecation header field value is in the past, the client
application developers MUST no longer assume that the behavior of the application developers MUST no longer assume that the behavior of the
resource would remain the same as before the deprecation date. In resource will remain the same as before the deprecation date. In
cases where the Deprecation header field value is a date in the cases where the Deprecation header field value is a date in the
future, it can lead to information that otherwise might not be future, it informs client application developers about the effective
available. Therefore, client application developers consuming the date in the future for deprecation. Therefore, client application
resource SHOULD, if possible, consult the resource developer to developers consuming the resource SHOULD, if possible, consult the
discuss potential impact due to deprecation and plan for possible resource developer to discuss potential impact due to deprecation and
transition to a recommended resource(s). plan for possible transition to a recommended resource(s).
8. Normative References 8. Normative References
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, [HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110, Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022, DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/rfc/rfc9110>. <https://www.rfc-editor.org/info/rfc9110>.
[LINK] Nottingham, M., "Web Linking", RFC 8288, [LINK] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017, DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/rfc/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/rfc/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8594] Wilde, E., "The Sunset HTTP Header Field", RFC 8594, [RFC8594] Wilde, E., "The Sunset HTTP Header Field", RFC 8594,
DOI 10.17487/RFC8594, May 2019, DOI 10.17487/RFC8594, May 2019,
<https://www.rfc-editor.org/rfc/rfc8594>. <https://www.rfc-editor.org/info/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 [RFC9651] Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
<https://www.rfc-editor.org/info/rfc9651>.
Appendix C. Acknowledgments Acknowledgments
The authors would like to thank Nikhil Kolekar, Darrel Miller, Mark The authors would like to thank Nikhil Kolekar, Darrel Miller, Mark
Nottingham, and Roberto Polli for their contributions. Nottingham, and Roberto Polli for their contributions.
The authors take all responsibility for errors and omissions. The authors take all responsibility for errors and omissions.
Authors' Addresses Authors' Addresses
Sanjay Dalal Sanjay Dalal
Email: sanjay.dalal@cal.berkeley.edu Email: sanjay.dalal@cal.berkeley.edu
 End of changes. 53 change blocks. 
300 lines changed or deleted 142 lines changed or added

This html diff was produced by rfcdiff 1.48.