HTTPAPI
Internet Engineering Task Force (IETF) S. Dalal
Internet-Draft
Intended status:
Request for Comments: 9745
Category: Standards Track E. Wilde
Expires: 31
ISSN: 2070-1721 March 2025 27 September 2024
The Deprecation HTTP Response 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 further
information about planned or existing deprecation, and possibly deprecation. It may also
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
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force
(IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list It represents the consensus of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid the IETF community. It has
received public review and has been approved for a maximum publication by the
Internet Engineering Steering Group (IESG). Further information on
Internet Standards is available in Section 2 of six months RFC 7841.
Information about the current status of this document, any errata,
and how to provide feedback on it may be updated, replaced, or obsoleted by other documents obtained 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.
https://www.rfc-editor.org/info/rfc9745.
Copyright Notice
Copyright (c) 2024 2025 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)
(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
has been deprecated. The Deprecation HTTP response header field can
be used to convey this information at runtime indicating and indicate when the
deprecation will be in effect.
In addition to the Deprecation header field, the resource provider
can use other header fields such as the Link ([LINK]) header field [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]) [RFC9651] 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 the context
of the message is or will be or has been deprecated.
2.1. Syntax
The Deprecation HTTP 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 in context will be deprecated at that
date) or in the past (the resource in context has been was 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]. [RFC9651].
The following example shows that the resource in context has been was
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 deprecation-related information different differently from its
standard meaning (i.e., it applies to the resource only).
Using such an increased scope still may make sense, as deprecation deprecation-
related 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 deprecation-related information. Increased scope information
may help client application developers to glean additional hints from
related resources and,
thus, and thus might allow them to implement behavior
that allows enables them to make educated guesses about resources becoming
deprecated.
For example, an API might not use Deprecation header fields on all of
its resources, resources but only on designated resources such as the API's home
document. This means that deprecation deprecation-related 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 response header field, the server
can use links with the "deprecation" 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,
deprecation to make a deprecation policy discoverable, discoverable or after
deprecation,
deprecation when there may be documentation about the deprecation, 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 a 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 deprecation-related
information. The documentation MAY provide a guide and timeline to
migrate for
migrating away from the deprecated resource to a new resource(s)
replacing that
replaces the deprecated resource, if applicable. The resource
provider can provide a link to the resource resource's documentation using a
Link header field with the relation type deprecation as shown below:
Link: <https://developer.example.com/deprecation>;
rel="deprecation"; type="text/html"
In this example example, the linked content provides additional information
about deprecation of the resource in context. There is no
Deprecation header field in the response, and thus response; 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. resource is
available. This may be the documentation explaining under which the
circumstances and with in which policies deprecation might take place. place and the
deprecation policies. 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. deprecated on the planned date. Or a policy
may indicate that the resource(s) would be deprecated first and then only
be signaled as deprecated at dedicated places. The documentation documentation, in
addition to the deprecation policy policy, may also provide a migration
guide exaplaining explaining 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 Link header field, 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 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 HTTP header field MUST NOT be
earlier than the one given in the Deprecation header field. If that
happens
for some reasons such as (for example, due to misconfiguration of deployment of the
resource or an error, error), the client application developer SHOULD
consult the resource developer to get clarification.
The following example shows that the resource in context has been was
deprecated since 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
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 a response is not meant
to signal a change in the meaning or function of a resource in the
context, allowing
context; consumers to can 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 HTTP response header field should be has been added to the
"Hypertext Transfer Protocol (HTTP) Field Name Registry" registry
(Section 16.3.1 of [HTTP])
Header as follows:
Field Name: Deprecation
Status: permanent
Structured Type: Item
Status: permanent
Specification document: this specification,
Reference: RFC 9745, Section 2 "The 2: The Deprecation HTTP Response Header Field"
Field
6.2. The Deprecation Link Relation Type
The deprecation link relation type should be has been added to the permanent "Link
Relation Types" registry of link relation types (Section 4.2 of [LINK]). [LINK]) as follows:
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,
Reference: RFC 9745, 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 (but not guaranteeing with certainty)
that it will be or is has been deprecated. Deprecated resources
function as they would have without sending the deprecation Deprecation header
field, even though one might consider non-functional details such as making them
progressively may be affected (e.g., they
have less efficient with efficiency and longer response time for example.
Resource times).
The resource's documentation should provide additional information
about the deprecation, such as including recommendation(s) recommendations for replacement.
Developers of client applications consuming the resource SHOULD
always check the referred resource resource's 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
private, or integrity-guaranteed, and so due caution should be exercised
when using it, see it (see Section 5 of [LINK] for more details. 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 will 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. informs client application developers about the effective
date in the future for deprecation. 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>.
<https://www.rfc-editor.org/info/rfc9110>.
[LINK] Nottingham, M., "Web Linking", RFC 8288,
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
Requirement Levels", BCP 14, RFC 2119,
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
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/rfc/rfc8174>. <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/rfc/rfc8594>.
[STRUCTURED-FIELDS]
<https://www.rfc-editor.org/info/rfc8594>.
[RFC9651] Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", Work in Progress, Internet-Draft, draft-ietf-
httpbis-sfbis-06, 21 April RFC 9651, DOI 10.17487/RFC9651, September 2024,
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
sfbis-06>.
Appendix C.
<https://www.rfc-editor.org/info/rfc9651>.
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