Draft: draft-ietf-httpapi-deprecation-header

Commentary: thanks a lot , this is very good and helpful !
The HTTP Deprecation Response Header Field can be used to signal to
consumers of a URI-identified resource that the resource has been
deprecated.  Additionally, the deprecation link relation can be used
to link to a resource that provides additional context for the
deprecation, and possibly ways in which clients can find a
replacement for the deprecated resource.
The Deprecation HTTP response header field can be used to signal to
consumers of a URI-identified resource that the resource has been
deprecated.  Additionally, the deprecation link relation can be used
to link to a resource that provides additional context for the
deprecation, and possibly ways in which clients can find a
replacement for the deprecated resource.
Deprecation of an HTTP resource as defined in Section 2 of RFC7231 is
a technique to communicate information about the lifecycle of a
resource.  It encourages applications to migrate away from the
resource, discourages applications from forming new dependencies on
the resource, and informs applications about the risk of continuing
dependence upon 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.
The Deprecation HTTP response header field MAY be used to convey this
fact at runtime to clients.  The header field can carry information
indicating since when the deprecation is in effect.
In addition to the Deprecation header field the resource provider can
use other header fields to convey additional information related to
deprecation.  For example, information such as where to find
documentation related to the deprecation or what should be used as an
alternate and when the deprecated resource would be unreachable, etc.
Alternates of a resource can be similar resource(s) or a newer
version of the same resource.
Deprecation of an HTTP resource (Section 2 of HTTP) communicates
information about the lifecycle of a resource.  It encourages
applications to migrate away from the resource, discourages
applications from forming new dependencies on the resource, and
informs applications about the risk of continuing dependence upon the
resource.
The act of deprecation does not change any behavior of the resource.
It informs clients of the fact that a resource is deprecated.  The
Deprecation HTTP response header field can be used to convey this at
runtime to clients, and can carry information indicating since when
the deprecation is in effect.
In addition to the Deprecation header field, the resource provider
can use other header fields to convey additional information related
to deprecation.  For example: information such as where to find
documentation related to the deprecation, what should be used as an
alternate, and when the deprecated resource would be unreachable.
Alternates can be similar resource(s) or a newer version of the same
resource.
This specification uses the Augmented Backus-Naur Form (ABNF)
notation of RFC5234 and includes, by reference, the IMF-fixdate rule
as defined in Section 7.1.1.1 of RFC7231.
The term "resource" is to be interpreted as defined in Section 2 of
RFC7231, that is identified by an URI.
This specification uses the Augmented Backus-Naur Form (ABNF)
notation of RFC5234 and includes, by reference, the IMF-fixdate rule
as defined in Section 7.1.1.1 of HTTP.
The term "resource" is to be interpreted as defined in Section 2 of
HTTP.
The date, if present, is the date when the resource context was or
will be deprecated.  It is in the form of an IMF-fixdate timestamp.
The deprecation date can be in the future.  If the value of "date" is
in the future, it means that the resource will be deprecated at the
given date in future.
The "Deprecation" response header field describes the deprecation of
the resource identified with the response it occured within (see
Section 3.1.4.1 of HTTP).  It conveys either 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), or it simply flags the resource context as
being deprecated.
The date, if present, is the date when the resource was or will be
deprecated.  It is in the form of an IMF-fixdate timestamp.
The deprecation date can be in the future.  This means that the
resource will be deprecated at the given date in future.
The Deprecation header field applies to the resource that returns it,
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.  However, 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).
The Deprecation header field applies to the resource identified with
the response it occured within (see Section 3.1.4.1 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).
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.
For a resource, deprecation could involve one or more parts of
request, response or both.  These parts could be one or more of the
following.
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.
In this example the interlinked content provides additional
information about the deprecation of the resource context.  There is
no Deprecation header field in the response, and thus the resource is
not deprecated.  However, the resource already exposes a link where
information is available how deprecation is managed for the context.
This may be documentation explaining the use of the Deprecation
header field, and also explaining under which circumstances and with
which policies (announcement before deprecation; continued operation
after deprecation) deprecation might be happening.
In this example the linked content provides additional information
about the deprecation of the resource context.  There is no
Deprecation header field in the response, and thus the resource is
not deprecated.  However, the resource already exposes a link where
information is available how deprecation is managed for the context.
This may be documentation explaining the use of the Deprecation
header field, and also explaining under which circumstances and with
which policies (announcement before deprecation; continued operation
after deprecation) deprecation might be happening.
The timestamp given in the "Sunset" header field MUST be the later or
the same as the one given in 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.
The "Deprecation" response header should be added to the permanent
registry of message header fields (see RFC3864), taking into account
the guidelines given by HTTP/1.1 RFC7231.
The "Deprecation" response header should be added to the permanent
registry of message header fields (see RFC3864).
The "deprecation" link relation type should be added to the permanent
registry of link relation types (Section 4.2 of LINK).
The suggested "Link" header fields make extensive use of IRIs and
URIs.  See RFC3987 for security considerations relating to IRIs.  See
RFC3986 for security considerations relating to URIs.  See RFC7230
for security considerations relating to HTTP headers.
The suggested "Link" header fields make extensive use of IRIs and
URIs.  See RFC3987 for security considerations relating to IRIs.  See
RFC3986 for security considerations relating to URIs.  See HTTP for
security considerations relating to HTTP headers.