draft-ietf-httpapi-link-hint-03.unpg.txt		draft-ietf-httpapi-link-hint-latest.txt
	Network Working Group M. Nottingham		Network Working Group M. Nottingham
	Internet-Draft May 18, 2025		Internet-Draft September 26, 2025
	Intended status: Standards Track		Intended status: Standards Track
	Expires: November 19, 2025		Expires: March 30, 2026
	HTTP Link Hints		HTTP Link Hints
	draft-ietf-httpapi-link-hint-03		draft-ietf-httpapi-link-hint-latest
	Abstract		Abstract
	This memo specifies "HTTP Link Hints", a mechanism for annotating Web		This memo specifies "HTTP Link Hints", a mechanism for annotating Web
	links to HTTP(S) resources with information that otherwise might be		links to HTTP(S) resources with information that otherwise might be
	discovered by interacting with them.		discovered by interacting with them.
	About This Document		About This Document
	This note is to be removed before publishing as an RFC.		This note is to be removed before publishing as an RFC.
	skipping to change at line 48 ¶		skipping to change at page 2, line 4 ¶
	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 March 30, 2026.
	This Internet-Draft will expire on November 19, 2025.
	Copyright Notice		Copyright Notice
	Copyright (c) 2025 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		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
	carefully, as they describe your rights and restrictions with respect		carefully, as they describe your rights and restrictions with respect
	to this document. Code Components extracted from this document must		to this document. Code Components extracted from this document must
	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		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	1.1. Notational Conventions		1.1. Notational Conventions . . . . . . . . . . . . . . . . . 3
	2. HTTP Link Hints		2. HTTP Link Hints . . . . . . . . . . . . . . . . . . . . . . . 4
	3. Pre-Defined HTTP Link Hints		3. Pre-Defined HTTP Link Hints . . . . . . . . . . . . . . . . . 4
	3.1. allow		3.1. allow . . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3.2. formats		3.2. formats . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3.3. accept-post		3.3. accept-post . . . . . . . . . . . . . . . . . . . . . . . 5
	3.4. accept-patch		3.4. accept-patch . . . . . . . . . . . . . . . . . . . . . . 5
	3.5. accept-ranges		3.5. accept-query . . . . . . . . . . . . . . . . . . . . . . 5
	3.6. accept-prefer		3.6. accept-ranges . . . . . . . . . . . . . . . . . . . . . . 6
	3.7. precondition-req		3.7. accept-prefer . . . . . . . . . . . . . . . . . . . . . . 6
	3.8. auth-schemes		3.8. precondition-req . . . . . . . . . . . . . . . . . . . . 7
	3.9. auth-realms		3.9. auth-schemes . . . . . . . . . . . . . . . . . . . . . . 7
	3.10. status		3.10. auth-realms . . . . . . . . . . . . . . . . . . . . . . . 7
	4. Security Considerations		3.11. status . . . . . . . . . . . . . . . . . . . . . . . . . 8
	5. IANA Considerations		4. Security Considerations . . . . . . . . . . . . . . . . . . . 8
	5.1. HTTP Link Hint Registry		5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
	6. References		5.1. HTTP Link Hint Registry . . . . . . . . . . . . . . . . . 8
	6.1. Normative References		6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
	6.2. Informative References		6.1. Normative References . . . . . . . . . . . . . . . . . . 9
	Appendix A. Acknowledgements		6.2. Informative References . . . . . . . . . . . . . . . . . 10
	Author's Address		Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 10
			Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11
	1. Introduction		1. Introduction
	HTTP [HTTP] clients can discover a variety of information about a		HTTP [HTTP] clients can discover a variety of information about a
	resource by interacting with it. For example, the methods supported		resource by interacting with it. For example, the methods supported
	by a resource can be learned by examining the Allow header field in		by a resource can be learned by examining the Allow header field in
	responses from it, and the need for authentication is conveyed with a		responses from it, and the need for authentication is conveyed with a
	401 (Authentication Required) status code.		401 (Authentication Required) status code.
	Often, it can be beneficial to know this information before		Often, it can be beneficial to know this information before
	skipping to change at line 129 ¶		skipping to change at page 3, line 37 ¶
	More fine-grained information might also be gathered by interacting		More fine-grained information might also be gathered by interacting
	with the resource (e.g., via a GET), or by another resource		with the resource (e.g., via a GET), or by another resource
	containing it (such as a widgets collection) or describing it (e.g.,		containing it (such as a widgets collection) or describing it (e.g.,
	one linked to it with a "describedby" link relation).		one linked to it with a "describedby" link relation).
	There is not a single way to convey hints with a link; rather, it is		There is not a single way to convey hints with a link; rather, it is
	expected that this will be done by individual link serialisations		expected that this will be done by individual link serialisations
	(see Section 3.4.1 of [WEB-LINKING]).		(see Section 3.4.1 of [WEB-LINKING]).
			Finally, these hints are not universally applicable to all links.
			Section 2.2 of [WEB-LINKING] specifies that the name space of target
			attributes for a given link is defined by both the link relation in
			use, and by the serialisation in use. Therefore, to be used in a
			given link, these hints need to be explicitly specified by either the
			link relation type or the serialisation (e.g., by referencing this
			specification).
	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.
	2. HTTP Link Hints		2. HTTP Link Hints
	skipping to change at line 174 ¶		skipping to change at page 4, line 42 ¶
	o Hint Name: allow		o Hint Name: allow
	o Description: Hints the HTTP methods that can be used to interact		o Description: Hints the HTTP methods that can be used to interact
	with the target resource; equivalent to the Allow HTTP response		with the target resource; equivalent to the Allow HTTP response
	header.		header.
	o Content Model: Inner List of Strings		o Content Model: Inner List of Strings
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Inner List of Strings, containing HTTP methods		Content MUST be an Inner List of Strings, containing HTTP methods
	(Section 9 of [HTTP]).		(Section 9 of [HTTP]).
	3.2. formats		3.2. formats
	o Hint Name: formats		o Hint Name: formats
	o Description: Hints the representation type(s) that the target		o Description: Hints the representation type(s) that the target
	resource can produce and consume, using the GET and PUT (if		resource can produce and consume, using the GET and PUT (if
	allowed) methods respectively.		allowed) methods respectively.
	o Content Model: Inner List of Strings		o Content Model: Inner List of Strings
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Inner List of Strings, containing media types		Content MUST be an Inner List of Strings, containing media types
	(Section 8.3.1 of [HTTP]).		(Section 8.3.1 of [HTTP]).
	3.3. accept-post		3.3. accept-post
	o Hint Name: accept-post		o Hint Name: accept-post
	o Description: Hints the POST request format(s) that the target		o Description: Hints the POST request format(s) that the target
	resource can consume.		resource can consume.
	o Content Model: Inner List of Strings		o Content Model: Inner List of Strings
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Inner List of Strings, with the same constraints as		Content MUST be an Inner List of Strings, with the same constraints
	for "formats".		as for "formats".
	When this hint is present, "POST" SHOULD be listed in the "allow"		When this hint is present, "POST" SHOULD be listed in the "allow"
	hint when present.		hint when present.
	3.4. accept-patch		3.4. accept-patch
	o Hint Name: accept-patch		o Hint Name: accept-patch
	o Description: Hints the PATCH [RFC5789] request format(s) that the		o Description: Hints the PATCH [PATCH] request format(s) that the
	target resource can consume; equivalent to the Accept-Patch HTTP		target resource can consume; equivalent to the Accept-Patch HTTP
	response header.		response header.
	o Content Model: Inner List of Strings		o Content Model: Inner List of Strings
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Inner List of Strings, containing media types		Content MUST be an Inner List of Strings, containing media types
	(Section 8.3.1 of [HTTP]) that identify the acceptable patch formats.		(Section 8.3.1 of [HTTP]) that identify the acceptable patch formats
			(see [PATCH]).
	When this hint is present, "PATCH" SHOULD be listed in the "allow"		When this hint is present, "PATCH" SHOULD be listed in the "allow"
	hint when present.		hint, when it is present.
	3.5. accept-ranges		3.5. accept-query
			o Hint name: accept-query
			o Description: Hints the QUERY [QUERY] request format(s) that the
			target resource can consume; equivalent to the Accept-Query HTTP
			response header.
			o Content Model: Inner List (of Strings)
			o Specification: [this document]
			Content MUST be an Inner List of Strings, containing media types
			(Section 8.3.1 of [HTTP]) that identify the acceptable query formats
			(see [QUERY]).
			When this hint is present, "QUERY" SHOLD be listed in the "allow"
			hint, when it is present.
			3.6. accept-ranges
	o Hint Name: accept-ranges		o Hint Name: accept-ranges
	o Description: Hints the range-specifier(s) available for the target		o Description: Hints the range-specifier(s) available for the target
	resource; equivalent to the Accept-Ranges HTTP response header		resource; equivalent to the Accept-Ranges HTTP response header
	[HTTP].		[HTTP].
	o Content Model: Inner List of Strings		o Content Model: Inner List of Strings
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Inner List of Strings, containing HTTP ranges-		Content MUST be an Inner List of Strings, containing HTTP ranges-
	specifiers (Section 14.1.1 of [HTTP]).		specifiers (Section 14.1.1 of [HTTP]).
	3.6. accept-prefer		3.7. accept-prefer
	o Hint Name: accept-prefer		o Hint Name: accept-prefer
	o Description: Hints the preference(s) [RFC7240] that the target		o Description: Hints the preference(s) [RFC7240] that the target
	resource understands (and might act upon) in requests.		resource understands (and might act upon) in requests.
	o Content Model: Inner List of Strings		o Content Model: Inner List of Strings
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Inner List of Strings, containing preferences		Content MUST be an Inner List of Strings, containing preferences
	(Section 2 of [RFC7240]). Note that, by its nature, a preference can		(Section 2 of [RFC7240]). Note that, by its nature, a preference can
	be ignored by the server.		be ignored by the server.
	3.7. precondition-req		3.8. precondition-req
	o Hint Name: precondition-req		o Hint Name: precondition-req
	o Description: Hints that the target resource requires state-		o Description: Hints that the target resource requires state-
	changing requests (e.g., PUT, PATCH) to include a precondition, as		changing requests (e.g., PUT, PATCH) to include a precondition, as
	per Section 13.1 of [HTTP], to avoid conflicts due to concurrent		per Section 13.1 of [HTTP], to avoid conflicts due to concurrent
	updates.		updates.
	o Content Model: Inner List of Strings		o Content Model: Inner List of Strings
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Inner List of Strings, with possible values "etag"		Content MUST be an Inner List of Strings, with possible values "etag"
	and "last-modified" indicating type of precondition expected.		and "last-modified" indicating type of precondition expected.
	See also the 428 Precondition Required status code ([RFC6585]).		See also the 428 Precondition Required status code ([RFC6585]).
	3.8. auth-schemes		3.9. auth-schemes
	o Hint Name: auth-schemes		o Hint Name: auth-schemes
	o Description: Hints that the target resource requires		o Description: Hints that the target resource requires
	authentication using the HTTP Authentication framework Section 11		authentication using the HTTP Authentication framework Section 11
	of [HTTP].		of [HTTP].
	o Content Model: Inner List of Strings		o Content Model: Inner List of Strings
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Inner List of Strings, each corresponding to a HTTP		Content MUST be an Inner List of Strings, each corresponding to a
	authentication scheme (Section 11.1 of [HTTP]), and optionally a		HTTP authentication scheme (Section 11.1 of [HTTP]).
	"realms" member containing an array of zero to many strings that
	identify protection spaces that the resource is a member of.
	3.9. auth-realms		3.10. auth-realms
	o Hint Name: auth-realms		o Hint Name: auth-realms
	o Description: Hints the authentication realm(s) available for those		o Description: Hints the authentication realm(s) available for those
	schemes that support them in the HTTP Authentication framework		schemes that support them in the HTTP Authentication framework
	Section 11 of [HTTP].		Section 11 of [HTTP].
	o Content Model: array (of strings)		o Content Model: Inner List (of Strings)
	o Specification: [this document]		o Specification: [this document]
	Content MUST be an array of strings, each indicating a protection		Content MUST be an Inner List of Strings, each indicating a
	space that the resource is a member of.		protection space that the resource is a member of.
	3.10. status		3.11. status
	o Hint Name: status		o Hint Name: status
	o Description: Hints the status of the target resource.		o Description: Hints the status of the target resource.
	o Content Model: Token		o Content Model: Token
	o Specification: [this document]		o Specification: [this document]
	Content MUST be a Token; possible values are:		Content MUST be a Token; possible values are:
	skipping to change at line 355 ¶		skipping to change at page 9, line 4 ¶
	(0-9), underscores ("_") and hyphens ("-"), and MUST begin with a		(0-9), underscores ("_") and hyphens ("-"), and MUST begin with a
	lowercase letter.		lowercase letter.
	Hint content MUST be described using valid combinations of the		Hint content MUST be described using valid combinations of the
	following types defined by HTTP Structured Fields		following types defined by HTTP Structured Fields
	([STRUCTURED-FIELDS]):		([STRUCTURED-FIELDS]):
	o Inner List (Section 3.1.2 of [STRUCTURED-FIELDS])		o Inner List (Section 3.1.2 of [STRUCTURED-FIELDS])
	o Item (Section 3.3 of [STRUCTURED-FIELDS])		o Item (Section 3.3 of [STRUCTURED-FIELDS])
	Hint semantics SHOULD be described in terms of the framework defined		Hint semantics SHOULD be described in terms of the framework defined
	in [WEB-LINKING].		in [WEB-LINKING].
	New hints are registered using the Expert Review process described in		New hints are registered using the IETF Review process described in
	[RFC8126] to enforce the criteria above. Requests for registration		[RFC8126]. Registration of new resource hints are to use the
	of new resource hints are to use the following template:		following template:
	o Hint Name: [hint name]		o Hint Name: [hint name]
	o Description: [a short description of the hint's semantics]		o Description: [a short description of the hint's semantics]
	o Content Model: [allowed Structured Fields types]		o Content Model: [allowed Structured Fields types]
	o Specification: [reference to specification document]		o Specification: [reference to specification document]
	Initial registrations are enumerated in Section 3. The "rel", "rev",		Initial registrations are enumerated in Section 3. Additionally, the
	"hreflang", "media", "title", and "type" hint names are reserved, so		"rel", "rev", "hreflang", "media", "title", and "type" hint names are
	as to avoid potential clashes with link serialisations.		reserved, so as to avoid potential clashes with link serialisations.
	6. References		6. References
	6.1. Normative References		6.1. 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>.
	skipping to change at line 400 ¶		skipping to change at page 9, line 48 ¶
	[JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data		[JSON] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
	Interchange Format", STD 90, RFC 8259,		Interchange Format", STD 90, RFC 8259,
	DOI 10.17487/RFC8259, December 2017,		DOI 10.17487/RFC8259, December 2017,
	<https://www.rfc-editor.org/info/rfc8259>.		<https://www.rfc-editor.org/info/rfc8259>.
	[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>.
	[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
	RFC 5789, DOI 10.17487/RFC5789, March 2010,
	<https://www.rfc-editor.org/info/rfc5789>.
	[RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status		[RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status
	Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012,		Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012,
	<https://www.rfc-editor.org/info/rfc6585>.		<https://www.rfc-editor.org/info/rfc6585>.
	[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240,		[RFC7240] Snell, J., "Prefer Header for HTTP", RFC 7240,
	DOI 10.17487/RFC7240, June 2014,		DOI 10.17487/RFC7240, June 2014,
	<https://www.rfc-editor.org/info/rfc7240>.		<https://www.rfc-editor.org/info/rfc7240>.
	[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,
	skipping to change at line 433 ¶		skipping to change at page 10, line 30 ¶
	RFC 3986, DOI 10.17487/RFC3986, January 2005,		RFC 3986, DOI 10.17487/RFC3986, January 2005,
	<https://www.rfc-editor.org/info/rfc3986>.		<https://www.rfc-editor.org/info/rfc3986>.
	[WEB-LINKING]		[WEB-LINKING]
	Nottingham, M., "Web Linking", RFC 8288,		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>.
	6.2. Informative References		6.2. Informative References
			[PATCH] Dusseault, L. and J. Snell, "PATCH Method for HTTP",
			RFC 5789, DOI 10.17487/RFC5789, March 2010,
			<https://www.rfc-editor.org/info/rfc5789>.
			[QUERY] Reschke, J., Snell, J., and M. Bishop, "The HTTP QUERY
			Method", draft-ietf-httpbis-safe-method-w-body-11 (work in
			progress), May 2025.
	[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for		[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
	Writing an IANA Considerations Section in RFCs", BCP 26,		Writing an IANA Considerations Section in RFCs", BCP 26,
	RFC 8126, DOI 10.17487/RFC8126, June 2017,		RFC 8126, DOI 10.17487/RFC8126, June 2017,
	<https://www.rfc-editor.org/info/rfc8126>.		<https://www.rfc-editor.org/info/rfc8126>.
	Appendix A. Acknowledgements		Appendix A. Acknowledgements
	Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne,		Thanks to Jan Algermissen, Mike Amundsen, Bill Burke, Graham Klyne,
	Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their		Leif Hedstrom, Jeni Tennison, Erik Wilde and Jorge Williams for their
	suggestions and feedback.		suggestions and feedback.
End of changes. 29 change blocks.
	62 lines changed or deleted		90 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/