rfc9745v1.txt		rfc9745.txt
	skipping to change at line 14 ¶		skipping to change at line 14 ¶
	Category: Standards Track E. Wilde		Category: Standards Track E. Wilde
	ISSN: 2070-1721 March 2025		ISSN: 2070-1721 March 2025
	The Deprecation HTTP Header Field		The Deprecation HTTP Header Field
	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 (in the sense of 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.
	Status of This Memo		Status of This Memo
	This is an Internet Standards Track document.		This is an Internet Standards Track document.
	This document is a product of the Internet Engineering Task Force		This document is a product of the Internet Engineering Task Force
	(IETF). It represents the consensus of the IETF community. It has		(IETF). It represents the consensus of the IETF community. It has
	received public review and has been approved for publication by the		received public review and has been approved for publication by the
	Internet Engineering Steering Group (IESG). Further information on		Internet Engineering Steering Group (IESG). Further information on
	Internet Standards is available in Section 2 of RFC 7841.		Internet Standards is available in Section 2 of RFC 7841.
	skipping to change at line 110 ¶		skipping to change at line 111 ¶
	[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 the context		communicate to a client application that the resource in the context
	of the message will be or has been 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 was deprecated at that		date) or in the past (the resource in context was deprecated at 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 [RFC9651].		Date as per Section 3.3.7 of [RFC9651].
	The following example shows that the resource context was deprecated		The following example shows that the resource in context was
	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 differently from its standard		interpret deprecation-related information differently from its
	meaning (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 thus		may help client application developers to glean additional hints from
	might allow them to implement behavior that enables 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 home		its resources but only on designated resources such as the API's home
	document. This means that deprecation information is available, but		document. This means that deprecation-related information is
	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 header field, the server can use
	links with the "deprecation" link relation type to communicate to the		links with the deprecation link relation type to communicate to the
	client application developer where to find more information about		client application developer where to find more information about
	deprecation of the context. This can happen before the actual		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 and		deprecation when there may be documentation about the deprecation 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 a 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 for		information. The documentation MAY provide a guide and timeline for
	migrating away from the deprecated resource to a new resource(s) that		migrating away from the deprecated resource to a new resource(s) that
	replaces 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 the 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; 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 describing how deprecation is managed for the resource is		information describing how deprecation is managed for the resource is
	available. 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 the resource(s) would be		places at least N days ahead of the planned deprecation date and then
	deprecated on the planned date. Or a policy may indicate that the		the resource(s) would be deprecated on the planned date. Or a policy
	resource(s) would be deprecated first and then be signaled as		may indicate that the resource(s) would be deprecated first and then
	deprecated at dedicated places. The documentation, in addition to		be signaled as deprecated at dedicated places. The documentation, in
	the deprecation policy, may also provide a migration guide explaining		addition to the deprecation policy, may also provide a migration
	to consumers of the resource how to migrate to a new or 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
	skipping to change at line 231 ¶		skipping to change at line 233 ¶
	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 example, due to misconfiguration of deployment of the resource		happens (for example, due to misconfiguration of deployment of the
	or an error), the client application developer SHOULD consult the		resource or an error), the client application developer SHOULD
	resource developer to get clarification.		consult the resource developer to get clarification.
	The following example shows that the resource in context was		The following example shows that the resource in context was
	deprecated on 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 a 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 has been added to the		The Deprecation HTTP response header field has been added to the
	"Hypertext Transfer Protocol (HTTP) Field Name Registry"		"Hypertext Transfer Protocol (HTTP) Field Name Registry"
	(Section 16.3.1 of [HTTP]) as follows:		(Section 16.3.1 of [HTTP]) as follows:
	Field Name: Deprecation		Field Name: Deprecation
	Status: permanent		Status: permanent
	Structured Type: Item		Structured Type: Item
	Reference: RFC 9745, Section 2: The Deprecation HTTP Header Field		Reference: RFC 9745, Section 2: The Deprecation HTTP Header Field
	6.2. The Deprecation Link Relation Type		6.2. The Deprecation Link Relation Type
	The deprecation link relation type has been added to the "Link		The deprecation link relation type has been added to the "Link
	Relation Types" registry (Section 4.2 of [LINK]) as follows:		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		Description: Refers to documentation (intended for human
	for human consumption) about the deprecation of the link's		consumption) about the deprecation of the link's context.
	context.
	Reference: RFC 9745, Section 3		Reference: RFC 9745, Section 3
	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 (but not guaranteeing with certainty)		that the resource is indicating (but not guaranteeing with certainty)
	that it will be or has been deprecated. Deprecated resources		that it will be or has been deprecated. Deprecated resources
	function as they would have without sending the Deprecation header		function as they would have without sending the Deprecation header
	field, even though one might consider non-functional details such as		field, even though non-functional details may be affected (e.g., they
	making them progressively less efficient with longer response time,		have less efficiency and longer response times).
	for example.
	Resource documentation should provide additional information about		The resource's documentation should provide additional information
	the deprecation, such as recommendations for replacement. Developers		about the deprecation, such as recommendations for replacement.
	of client applications consuming the resource SHOULD always check the		Developers of client applications consuming the resource SHOULD
	referred resource documentation to verify authenticity and accuracy.		always check the referred resource's documentation to verify
	In cases where a Link header field is used to provide documentation,		authenticity and accuracy. In cases where a Link header field is
	one should assume (unless served over HTTPS) that the content of the		used to provide documentation, one should assume (unless served over
	Link header field may not be secure, private, or integrity-		HTTPS) that the content of the Link header field may not be secure,
	guaranteed, so due caution should be exercised when using it (see		private, or integrity-guaranteed, so due caution should be exercised
	Section 5 of [LINK] for more details). In cases where the		when using it (see Section 5 of [LINK] for more details). In cases
	Deprecation header field value is in the past, the client application		where the Deprecation header field value is in the past, the client
	developers MUST no longer assume that the behavior of the resource		application developers MUST no longer assume that the behavior of the
	will remain the same as before the deprecation date. In cases where		resource will remain the same as before the deprecation date. In
	the Deprecation header field value is a date in the future, it can		cases where the Deprecation header field value is a date in the
	lead to information that otherwise might not be available.		future, it informs client application developers about the effective
	Therefore, client application developers consuming the resource		date in the future for deprecation. Therefore, client application
	SHOULD, if possible, consult the resource developer to discuss		developers consuming the resource SHOULD, if possible, consult the
	potential impact due to deprecation and plan for possible transition		resource developer to discuss potential impact due to deprecation and
	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/info/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,
End of changes. 18 change blocks.
	73 lines changed or deleted		73 lines changed or added
This html diff was produced by rfcdiff 1.48.