< draft-dalal-deprecation-header-00.txt   draft-dalal-deprecation-header-01.txt >
Network Working Group S. Dalal Network Working Group S. Dalal
Internet-Draft Internet-Draft
Intended status: Standards Track E. Wilde Intended status: Standards Track E. Wilde
Expires: August 30, 2019 February 26, 2019 Expires: December 19, 2019 June 17, 2019
The Deprecation HTTP Header The Deprecation HTTP Header Field
draft-dalal-deprecation-header-00 draft-dalal-deprecation-header-01
Abstract Abstract
The HTTP Deprecation response header can be used to signal to The HTTP Deprecation response header field can be used to signal to
consumers of a URI-identified resource that the use of the resource consumers of a URI-identified resource that the resource has been
has been deprecated. Additionally, the deprecation link relation can deprecated. Additionally, the deprecation link relation can be used
be used to link to a resource that provides additional context for to link to a resource that provides additional context for the
the deprecation, and possibly ways in which clients can find a deprecation, and possibly ways in which clients can find a
replacement for the deprecated resource. replacement for the deprecated resource.
Status of This Memo Status of This Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 30, 2019. This Internet-Draft will expire on December 19, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 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 Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 13 skipping to change at page 2, line 13
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
2. The Deprecation HTTP Response Header Field . . . . . . . . . 3 2. The Deprecation HTTP Response Header Field . . . . . . . . . 3
2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1.1. Version . . . . . . . . . . . . . . . . . . . . . . . 4 3. The Deprecation Link Relation Type . . . . . . . . . . . . . 4
2.1.2. Date . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Documentation . . . . . . . . . . . . . . . . . . . . . . 4
3. The Deprecation Link Relation Type . . . . . . . . . . . . . 5 4. Recommend Replacement . . . . . . . . . . . . . . . . . . . . 5
3.1. Documentation . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Policy . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Recommend Replacement . . . . . . . . . . . . . . . . . . . . 6
5. Sunset . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 5. Sunset . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 6. Resource Behavior . . . . . . . . . . . . . . . . . . . . . . 6
6.1. The Deprecation Response Header Field . . . . . . . . . . 7 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
6.2. The Deprecation Link Relation Type . . . . . . . . . . . 7 7.1. The Deprecation Response Header Field . . . . . . . . . . 6
7. Implementation Status . . . . . . . . . . . . . . . . . . . . 8 7.2. The Deprecation Link Relation Type . . . . . . . . . . . 7
8. Security Considerations . . . . . . . . . . . . . . . . . . . 9 8. Implementation Status . . . . . . . . . . . . . . . . . . . . 7
9. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 9. Security Considerations . . . . . . . . . . . . . . . . . . . 8
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 10. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 9
10.1. Normative References . . . . . . . . . . . . . . . . . . 10 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
10.2. Informative References . . . . . . . . . . . . . . . . . 11 11.1. Normative References . . . . . . . . . . . . . . . . . . 9
11.2. Informative References . . . . . . . . . . . . . . . . . 11
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 11 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction 1. Introduction
Deprecation of a URI-identified resource is a technique to Deprecation of a URI-identified resource is a technique to
communicate information about the lifecycle of a resource. It communicate information about the lifecycle of a resource. It
encourages applications to migrate away from the resource and encourages applications to migrate away from the resource,
discourage applications from forming new dependencies on the discourages applications from forming new dependencies on the
resource, and informs applications of the risk of continuing resource, and informs applications about the risk of continuing
dependence upon the resource. dependence upon the 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 just informs client of the fact that a resource is deprecated. It just informs client of the fact that a resource is deprecated.
The Deprecation HTTP response header field MAY be used to convey this The Deprecation HTTP response header field MAY be used to convey this
fact at runtime to clients. The header field can carry additional fact at runtime to clients. The header field can carry information
information such as since when the deprecation is in effect. indicating since when the deprecation is in effect.
In addition to the Deprecation header field the resource provider can In addition to the Deprecation header field the resource provider can
use other header fields to convey additional information related to use other header fields to convey additional information related to
deprecation. For example, information such as where to find deprecation. For example, information such as where to find
documentation related to the deprecation or what should be used as an documentation related to the deprecation or what should be used as an
alternate and when the deprecated resource would be unreachable, etc. alternate and when the deprecated resource would be unreachable, etc.
Alternates of a resource can be similar resource(s) or a newer Alternates of a resource can be similar resource(s) or a newer
version of the same resource. version of the same resource.
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 BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
skipping to change at page 3, line 17 skipping to change at page 3, line 14
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 BCP "OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
This specification uses the Augmented Backus-Naur Form (ABNF) This specification uses the Augmented Backus-Naur Form (ABNF)
notation of [RFC5234] and includes, by reference, the "token" rule, notation of [RFC5234] and includes, by reference, the HTTP-date rule
DQUOTE (double quote) rule, the SP (space) rule and the "rule" as defined within Sections 3.2.6 and 7 of [RFC7230] and Section 7.1.1
extension that allows for compact definition of comma-separated lists of [RFC7231].
using a '#' operator (similar to how the '*' operator indicates
repetition), HTTP-date rule as defined within Sections 3.2.6 and 7 of
[RFC7230] and Section 7.1.1 of [RFC7231].
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 that the URI-identified resource in context communicate to a client that the URI-identified resource in context
of the message is deprecated. It can also provide information that of the message is or will be deprecated.
the resource is deprecated since which version.
2.1. Syntax 2.1. Syntax
The "Deprecation" response header contains the header name The "Deprecation" response header field describes the deprecation.
"Deprecation" followed by a ":" and a property(s). Each property It either shows the deprecation date, which may be in the future (the
consists of a name-value-pair. Servers SHOULD NOT send Deprecation resource context will be deprecated at that date) or in the past (the
headers that fail to conform to the following grammar: resource context has been deprecated at that date), or it simply
flags the resource context as being deprecated:
deprecation-header = "Deprecation:" SP "version"=vval, "date"=dval,
*( extension )
extension = property-name "=" property-value
property-name = DQUOTE token DQUOTE
token = <token, defined as in [RFC7230], Section 3.2.6>
vval = property-value
property-value = DQUOTE *( pchar ) DQUOTE
pchar = %x23 / %x2B-3A / %x41-5A / %x61-7A / %x7C
; US-ASCII characters
dval = DQUOTE HTTP-date DQUOTE
Note that some of the grammatical terms above reference documents
that use different grammatical notations than this document (which
uses ABNF from [RFC5234]).
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.
Deprecation: version="version", date="date"
2.1.1. Version
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.
Deprecation: version="v1" Deprecation = HTTP-date / "true"
Following example shows that the version 2018-11-08 (November 8, Servers MUST NOT include more than one "Deprecation" header field in
2018) of the resource in context is deprecated. Here the versioning the same response.
scheme used is date-based.
Deprecation: version="2018-11-08" The date, if present, is the date when the resource context was or
will be deprecated. It is in the form of an HTTP-date timestamp, as
defined in Section 7.1.1.1 of [RFC7231].
2.1.2. Date The following example shows that the resource context has been
deprecated on Friday, November 11, 2018 at 23:59:59 GMT:
The value of "date" property, if present, would be the date when Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
resource was deprecated. It would be in the form of a quoted HTTP-
date timestamp, as defined in Section 7.1.1.1 of [RFC7231].
Following example shows that the resource in context is deprecated on The deprecation date can be in the future. If the value of "date" is
Friday, November 11, 2018 at 23:59:59 GMT. in the future, it means that the resource will be deprecated at the
given date in future.
Deprecation: date="Fri, 11 Nov 2018 23:59:59 GMT" If the deprecation date is not known, the header field can carry the
simple string "true", indicating that the resource context is
deprecated, without indicating when that happened:
Date could be in future too. If the value of "date" is in future, it Deprecation: true
means that the resource would be deprecated on the given date in
future.
3. The Deprecation Link Relation Type 3. The Deprecation Link Relation Type
In addition to the Deprecation HTTP header, the server could use a In addition to the Deprecation HTTP header field, the server can use
"Link" header(s) to communicate to the client where to find more links with the "deprecation" link relation type to communicate to the
information about deprecation of the resource in context. This client where to find more information about deprecation of the
information could be in the form of documentation of the resource context. This can happen before the actual deprecation, to make a
including details about the deprecation related aspects of the deprecation policy discoverable, or after deprecation, when there may
resource or the deprecation policy of the resource provider or both be documentation about the deprecation, and possibly documentation of
for example. how to manage it.
This specification places no restrictions on the representation of
the interlinked deprecation policy. In particular, the deprecation
policy may be available as human-readable documentation or as
machine-readable description.
3.1. Documentation 3.1. Documentation
For a URI-identified resource, deprecation could involve one or more For a URI-identified resource, deprecation could involve one or more
parts of request, response or both. These parts could be one or more parts of request, response or both. These parts could be one or more
of the following. of the following.
o URI - deprecation of one ore more query parameter(s) or path o URI - deprecation of one ore more query parameter(s) or path
element(s) element(s)
skipping to change at page 5, line 44 skipping to change at page 4, line 51
element(s) element(s)
The purpose of the "Deprecation" header is to provide just enough The purpose of the "Deprecation" header is to provide just enough
"hints" about the deprecation to the client application developer. "hints" about the deprecation to the client application developer.
It is safe to assume that on reception of the "Deprecation" header, It is safe to assume that on reception of the "Deprecation" header,
the client developer would look up the resource's documentation in the client developer would look up the resource's documentation in
order to find deprecation related semantics. The resource developer order to find deprecation related semantics. The resource developer
could provide a link to the resource documentation using a "Link" could provide a link to the resource documentation using a "Link"
header with relation type "deprecation" as shown below. header with relation type "deprecation" as shown below.
Deprecation: version="v1" Link: <https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"
Link: <https://developer.example.com/v1/customers>; rel="deprecation" In this example, the interlinked content provides additional
type="text/html" information about the deprecation of the resource context. In this
example, there is no Deprecation header field in the response, and
where content at "https://developer.example.com/v1/customers" would thus the resource is not deprecated. However, the resource already
be annotated to show deprecation of the relevant parts of the exposes a link where information is available how deprecation is
"customers" resource. managed for the context. This may be documentation explaining the
use of the Deprecation header field, and also explaining under which
3.2. Policy circumstances and with which policies (announcement before
deprecation; continued operation after deprecation) deprecation might
be happening.
Resource provider would typically document versioning and deprecation The following example uses the same link header, but also announces a
policy with the resource documentation. To inform the client deprecation date using a Deprecation header field.
application developer of the deprecation policy, the resource
provider could use the "deprecation" relation type as shown below.
Deprecation: version="v1" Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://developer.example.com/deprecation>; rel="deprecation" Link: <https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"
type="text/html"
where deprecation policy of the resource provider "example.com" is Given that the deprecation date is in the past, the linked resource
described at "https://developer.example.com/deprecation". may have been updated to include information about the deprecation,
allowing clients to discover information about the deprecation that
happened.
4. Recommend Replacement 4. Recommend Replacement
"Link" [RFC8288] header could be used in addition to the "Link" [RFC8288] header could be used in addition to the
"Deprecation" header to recommend the client application about "Deprecation" header to recommend the client application about
available alternates to the deprecated resource. Following relation available alternates to the deprecated resource. Following relation
types as defined in [RFC8288] are RECOMMENDED to use for the purpose. types as defined in [RFC8288] are RECOMMENDED to use for the purpose.
o "successor-version": Points to a resource containing the successor o "successor-version": Points to a resource containing the successor
version. [RFC5829] version. [RFC5829]
o "latest-version": Points to a resource containing the latest o "latest-version": Points to a resource containing the latest
(e.g., current) version. [RFC5829] (e.g., current) version. [RFC5829]
o "alternate": Designates a substitute. [W3C.REC-html401-19991224] o "alternate": Designates a substitute. [W3C.REC-html401-19991224]
Following example provides link to the successor version of the v1 The following example provides link to the successor version of the
version of "customer" resource that is deprecated. requested resource that is deprecated.
Deprecation: version="v1" Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version" Link: <https://api.example.com/v2/customers>; rel="successor-version"
This example provides link to an alternate resource to the "customer" This example provides link to an alternate resource to the requested
resource that is deprecated. resource that is deprecated.
Deprecation: version="2018-11-11" Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://api.example.com/v1/clients>; rel="alternate" Link: <https://api.example.com/v1/clients>; rel="alternate"
5. Sunset 5. 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] header could be used in addition to the point in time, the [RFC8594] header could be used in addition to the
"Deprecation" header. "Deprecation" header.
Following example indicates that the resource in context has been The following example shows 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.
Deprecation: version="v2"
Sunset: Fri, 11 Nov 2020 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 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. sunset date is Friday, November 11, 2020 at 23:59:59 GMT.
Deprecation: date="Fri, 11 Nov 2018 23:59:59 GMT" Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Sunset: Fri, 11 Nov 2020 23:59:59 GMT Sunset: Wed, 11 Nov 2020 23:59:59 GMT
6. IANA Considerations 6. Resource Behavior
6.1. The Deprecation Response Header Field The act of deprecation does not change any behavior of the resource.
Deprecated resources SHOULD keep functioning as before, allowing
consumers to still use the resources in the same way as they did
before the resources were declared deprecated.
7. IANA Considerations
7.1. The Deprecation Response Header Field
The "Deprecation" response header should be added to the permanent The "Deprecation" response header should be added to the permanent
registry of message header fields (see [RFC3864]), taking into registry of message header fields (see [RFC3864]), taking into
account the guidelines given by HTTP/1.1 [RFC7231]. account the guidelines given by HTTP/1.1 [RFC7231].
Header Field Name: Deprecation Header Field Name: Deprecation
Applicable Protocol: Hypertext Transfer Protocol (HTTP) Applicable Protocol: Hypertext Transfer Protocol (HTTP)
Status: Standard Status: Standard
Author: Sanjay Dalal <sanjay.dalal@cal.berkeley.edu>, Author: Sanjay Dalal <sanjay.dalal@cal.berkeley.edu>,
Erik Wilde <erik.wilde@dret.net> Erik Wilde <erik.wilde@dret.net>
Change controller: IETF Change controller: IETF
Specification document: this specification, Specification document: this specification,
Section 2 "The Deprecation HTTP Response Header Field" Section 2 "The Deprecation HTTP Response Header Field"
6.2. The Deprecation Link Relation Type 7.2. The Deprecation Link Relation Type
The "deprecation" link relation type should be added to the permanent The "deprecation" link relation type should be added to the permanent
registry of link relation types according to Section 4.2 of registry of link relation types according to Section 4.2 of
[RFC8288]: [RFC8288]:
Relation Type: deprecation Relation Type: deprecation
Applicable Protocol: Hypertext Transfer Protocol (HTTP) Applicable Protocol: Hypertext Transfer Protocol (HTTP)
Status: Standard Status: Standard
Author: Sanjay Dalal <sanjay.dalal@cal.berkeley.edu>, Author: Sanjay Dalal <sanjay.dalal@cal.berkeley.edu>,
Erik Wilde <erik.wilde@dret.net> Erik Wilde <erik.wilde@dret.net>
Change controller: IETF Change controller: IETF
Specification document: this specification, Specification document: this specification,
Section 3 "The Deprecation Link Relation Type" Section 3 "The Deprecation Link Relation Type"
7. Implementation Status 8. Implementation Status
Note to RFC Editor: Please remove this section before publication. Note to RFC Editor: Please remove this section before publication.
This section records the status of known implementations of the This section records the status of known implementations of the
protocol defined by this specification at the time of posting of this protocol defined by this specification at the time of posting of this
Internet-Draft, and is based on a proposal described in [RFC7942]. Internet-Draft, and is based on a proposal described in [RFC7942].
The description of implementations in this section is intended to The description of implementations in this section is intended to
assist the IETF in its decision processes in progressing drafts to assist the IETF in its decision processes in progressing drafts to
RFCs. Please note that the listing of any individual implementation RFCs. Please note that the listing of any individual implementation
here does not imply endorsement by the IETF. Furthermore, no effort here does not imply endorsement by the IETF. Furthermore, no effort
skipping to change at page 9, line 29 skipping to change at page 8, line 35
Reference: https://blog.clearbit.com/dealing-with-deprecation/ Reference: https://blog.clearbit.com/dealing-with-deprecation/
Organization: PayPal Organization: PayPal
Description: PayPal uses a custom HTTP header named "PayPal- Description: PayPal uses a custom HTTP header named "PayPal-
Deprecated" Deprecated"
Reference: https://github.com/paypal/api-standards/blob/master/api- Reference: https://github.com/paypal/api-standards/blob/master/api-
style-guide.md#runtime style-guide.md#runtime
8. Security Considerations 9. Security Considerations
The content of a "Link" header field is not secure, private or The Deprecation header field SHOULD be treated as a hint, meaning
that the resource is indicating (and not guaranteeing with certainty)
that it is deprecated. Applications consuming the resource SHOULD
check the resource documentation to verify authenticity and accuracy.
Resource documentation SHOULD provide additional information about
the deprecation including recommendation(s) for replacement.
In cases, where the Deprecation header field value is a date in
future, it can lead to information that otherwise might not be
available. Therefore, applications consuming the resource SHOULD
verify the resource documentation and if possible, consult the
resource developer to discuss potential impact due to deprecation and
plan for possible transition to recommended resource.
In cases where "Link" header is used to provide more documentation
and/or recommendation for replacement, one should assume that the
content of the "Link" header field may not be secure, private or
integrity-guaranteed, and due caution should be exercised when using integrity-guaranteed, and due caution should be exercised when using
it. Use of Transport Layer Security (TLS) with HTTP ([RFC7230] is it. Applications consuming the resource SHOULD check the referred
currently the only end-to-end way to provide such protection. resource documentation to verify authenticity and accuracy.
The suggested "Link" header fields make extensive use of IRIs and The suggested "Link" header fields make extensive use of IRIs and
URIs. See [RFC3987] for security considerations relating to IRIs. URIs. See [RFC3987] for security considerations relating to IRIs.
See [RFC3986] for security considerations relating to URIs. See See [RFC3986] for security considerations relating to URIs. See
[RFC7230] for security considerations relating to HTTP headers. [RFC7230] for security considerations relating to HTTP headers.
Applications that take advantage of typed links should consider the Applications that take advantage of typed links should consider the
attack vectors opened by automatically following, trusting, or attack vectors opened by automatically following, trusting, or
otherwise using links gathered from the HTTP headers. In particular, otherwise using links gathered from the HTTP headers. In particular,
Link headers that use the "successor-version", "latest-version" or Link headers that use the "successor-version", "latest-version" or
"alternate" relation types should be treated with due caution. See "alternate" relation types should be treated with due caution. See
[RFC5829] for security considerations relating to these link relation [RFC5829] for security considerations relating to these link relation
types. types.
9. Example 10. Examples
Just deprecation header without any Link headers. The first example shows a deprecation header field without date
information:
Deprecation: version="v1" Deprecation: true
Deprecation header with link to the successor version. The second example shows a deprecation header with date information
and a link to the successor version:
Deprecation: version="v1" Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version" Link: <https://api.example.com/v2/customers>; rel="successor-version"
Deprecation header with links for the successor version and for the The third example shows a deprecation header field with links for the
API developer's deprecation policy. Also, it shows sunset date for successor version and for the API's deprecation policy. In addition,
the deprecated version (v1). it shows the sunset date for the deprecated resource:
Deprecation: version="v1" Deprecation: Sun, 11 Nov 2018 23:59:59 GMT
Sunset: Fri, 11 Nov 2020 23:59:59 GMT Sunset: Wed, 11 Nov 2020 23:59:59 GMT
Link: <https://api.example.com/v2/customers>; rel="successor-version" Link: <https://api.example.com/v2/customers>; rel="successor-version", <https://developer.example.com/deprecation>; rel="deprecation"
Link: <https://developer.example.com/deprecation>; rel="deprecation"
10. References 11. References
10.1. Normative References 11.1. Normative References
[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/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
[RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration [RFC3864] Klyne, G., Nottingham, M., and J. Mogul, "Registration
Procedures for Message Header Fields", BCP 90, RFC 3864, Procedures for Message Header Fields", BCP 90, RFC 3864,
DOI 10.17487/RFC3864, September 2004, DOI 10.17487/RFC3864, September 2004,
<https://www.rfc-editor.org/info/rfc3864>. <https://www.rfc-editor.org/info/rfc3864>.
skipping to change at page 11, line 28 skipping to change at page 11, line 5
<https://www.rfc-editor.org/info/rfc7234>. <https://www.rfc-editor.org/info/rfc7234>.
[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/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8288] Nottingham, M., "Web Linking", RFC 8288, [RFC8288] Nottingham, M., "Web Linking", RFC 8288,
DOI 10.17487/RFC8288, October 2017, DOI 10.17487/RFC8288, October 2017,
<https://www.rfc-editor.org/info/rfc8288>. <https://www.rfc-editor.org/info/rfc8288>.
10.2. Informative References 11.2. Informative References
[Deprecation]
Marks, S., "JEP 277 - Enhanced Deprecation", 2017,
<http://openjdk.java.net/jeps/277>.
[RFC5829] Brown, A., Clemm, G., and J. Reschke, Ed., "Link Relation [RFC5829] Brown, A., Clemm, G., and J. Reschke, Ed., "Link Relation
Types for Simple Version Navigation between Web Types for Simple Version Navigation between Web
Resources", RFC 5829, DOI 10.17487/RFC5829, April 2010, Resources", RFC 5829, DOI 10.17487/RFC5829, April 2010,
<https://www.rfc-editor.org/info/rfc5829>. <https://www.rfc-editor.org/info/rfc5829>.
[RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", BCP 205, Code: The Implementation Status Section", BCP 205,
RFC 7942, DOI 10.17487/RFC7942, July 2016, RFC 7942, DOI 10.17487/RFC7942, July 2016,
<https://www.rfc-editor.org/info/rfc7942>. <https://www.rfc-editor.org/info/rfc7942>.
[Sunset] Wilde, E., "The Sunset HTTP Header Field", 2019, [RFC8594] Wilde, E., "The Sunset HTTP Header Field", RFC 8594,
<https://tools.ietf.org/html/ DOI 10.17487/RFC8594, May 2019,
draft-wilde-sunset-header-11>. <https://www.rfc-editor.org/info/rfc8594>.
Appendix A. Acknowledgments Appendix A. Acknowledgments
The authors would like to thank Mark Nottingham and Nikhil Kolekar The authors would like to thank Mark Nottingham and Nikhil Kolekar
for reviewing this specification. for reviewing this specification.
The authors take all responsibility for errors and omissions. The authors take all responsibility for errors and omissions.
Authors' Addresses Authors' Addresses
 End of changes. 51 change blocks. 
167 lines changed or deleted 143 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/