draft-ietf-httpbis-safe-method-w-body-07.txt		draft-ietf-httpbis-safe-method-w-body-latest.txt
	HTTP Working Group J. Reschke		HTTP Working Group J. Reschke
	Internet-Draft greenbytes		Internet-Draft greenbytes
	Intended status: Standards Track A. Malhotra		Intended status: Standards Track A. Malhotra
	Expires: June 21, 2025		Expires: August 7, 2025
	J.M. Snell		J.M. Snell
	M. Bishop		M. Bishop
	Akamai		Akamai
	December 18, 2024		February 3, 2025
	The HTTP QUERY Method		The HTTP QUERY Method
	draft-ietf-httpbis-safe-method-w-body-07		draft-ietf-httpbis-safe-method-w-body-latest
	Abstract		Abstract
	This specification defines a new HTTP method, QUERY, as a safe,		This specification defines a new HTTP method, QUERY, as a safe,
	idempotent request method that can carry request content.		idempotent request method that can carry request content.
	Editorial Note		Editorial Note
	This note is to be removed before publishing as an RFC.		This note is to be removed before publishing as an RFC.
	Discussion of this draft takes place on the HTTP working group		Discussion of this draft takes place on the HTTP working group
	mailing list (ietf-http-wg@w3.org), which is archived at		mailing list (ietf-http-wg@w3.org), which is archived at
	<https://lists.w3.org/Archives/Public/ietf-http-wg/>.		<https://lists.w3.org/Archives/Public/ietf-http-wg/>.
	Working Group information can be found at <https://httpwg.org/>;		Working Group information can be found at <https://httpwg.org/>;
	source code and issues list for this draft can be found at		source code and issues list for this draft can be found at
	<https://github.com/httpwg/http-extensions/labels/query-method>.		<https://github.com/httpwg/http-extensions/labels/query-method>.
	The changes in this draft are summarized in Appendix B.7.		The changes in this draft are summarized in Appendix B.8.
	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 June 21, 2025.		This Internet-Draft will expire on August 7, 2025.
	Copyright Notice		Copyright Notice
	Copyright (c) 2024 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 (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	and restrictions with respect to this document. Code Components		and restrictions with respect to this document. Code Components
	extracted from this document must include Revised BSD License text as		extracted from this document must include Revised BSD License text as
	described in Section 4.e of the Trust Legal Provisions and are		described in Section 4.e of the Trust Legal Provisions and are
	provided without warranty as described in the Revised BSD License.		provided without warranty as described in the Revised BSD License.
	skipping to change at page 2, line 30 ¶		skipping to change at page 2, line 30 ¶
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
	1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4		1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
	1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4		1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4
	2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5		2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
	2.1. Content-Location and Location Fields . . . . . . . . . . 5		2.1. Content-Location and Location Fields . . . . . . . . . . 5
	2.2. Redirection . . . . . . . . . . . . . . . . . . . . . . . 6		2.2. Redirection . . . . . . . . . . . . . . . . . . . . . . . 6
	2.3. Conditional Requests . . . . . . . . . . . . . . . . . . 6		2.3. Conditional Requests . . . . . . . . . . . . . . . . . . 6
	2.4. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 6		2.4. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 6
			2.5. Range Requests . . . . . . . . . . . . . . . . . . . . . 7
	3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 7		3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 7
	4. Security Considerations . . . . . . . . . . . . . . . . . . . 7		4. Security Considerations . . . . . . . . . . . . . . . . . . . 8
	5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8		5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
	5.1. Registration of QUERY method . . . . . . . . . . . . . . 8		5.1. Registration of QUERY method . . . . . . . . . . . . . . 8
	5.2. Registration of Accept-Query field . . . . . . . . . . . 8		5.2. Registration of Accept-Query field . . . . . . . . . . . 8
	6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9		6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
	6.1. Normative References . . . . . . . . . . . . . . . . . . 9		6.1. Normative References . . . . . . . . . . . . . . . . . . 9
	6.2. Informative References . . . . . . . . . . . . . . . . . 9		6.2. Informative References . . . . . . . . . . . . . . . . . 9
	Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10		Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10
	A.1. Simple QUERY with a Direct Response . . . . . . . . . . . 10		A.1. Simple QUERY with a Direct Response . . . . . . . . . . . 10
	A.2. Simple QUERY with a Direct Response and Location		A.2. Simple QUERY with a Direct Response and Location
	Fields . . . . . . . . . . . . . . . . . . . . . . . . . 10		Fields . . . . . . . . . . . . . . . . . . . . . . . . . 10
	skipping to change at page 3, line 5 ¶		skipping to change at page 3, line 6 ¶
	A.4. Simple QUERY with Redirect Response (308 Moved		A.4. Simple QUERY with Redirect Response (308 Moved
	Permanently) . . . . . . . . . . . . . . . . . . . . . . 12		Permanently) . . . . . . . . . . . . . . . . . . . . . . 12
	Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 13		Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 13
	B.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 13		B.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 13
	B.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 13		B.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 13
	B.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 13		B.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 13
	B.4. Since draft-ietf-httpbis-safe-method-w-body-03 . . . . . 14		B.4. Since draft-ietf-httpbis-safe-method-w-body-03 . . . . . 14
	B.5. Since draft-ietf-httpbis-safe-method-w-body-04 . . . . . 14		B.5. Since draft-ietf-httpbis-safe-method-w-body-04 . . . . . 14
	B.6. Since draft-ietf-httpbis-safe-method-w-body-05 . . . . . 14		B.6. Since draft-ietf-httpbis-safe-method-w-body-05 . . . . . 14
	B.7. Since draft-ietf-httpbis-safe-method-w-body-06 . . . . . 14		B.7. Since draft-ietf-httpbis-safe-method-w-body-06 . . . . . 14
			B.8. Since draft-ietf-httpbis-safe-method-w-body-07 . . . . . 15
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15
	1. Introduction		1. Introduction
	This specification defines the HTTP QUERY request method as a means		This specification defines the HTTP QUERY request method as a means
	of making a safe, idempotent request that contains content.		of making a safe, idempotent request that contains content.
	Most often, this is desirable when the data conveyed in a request is		Most often, this is desirable when the data conveyed in a request is
	too voluminous to be encoded into the request's URI. For example,		too voluminous to be encoded into the request's URI. For example,
	this is a common query pattern:		this is a common query pattern:
	GET /feed?q=foo&limit=10&sort=-published HTTP/1.1		GET /feed?q=foo&limit=10&sort=-published HTTP/1.1
	Host: example.org		Host: example.org
	However, for a query with parameters that are complex or large in		However, for a query with parameters that are complex or large,
	size, encoding it in the request URI may not be the best option		encoding it in the request URI may not be the best option because
	because
	o often size limits are not known ahead of time because a request		o often size limits are not known ahead of time because a request
	can pass through many uncoordinated system (but note that		can pass through many uncoordinated system (but note that
	Section 4.1 of [HTTP] recommends senders and recipients to support		Section 4.1 of [HTTP] recommends senders and recipients to support
	at least 8000 octets),		at least 8000 octets),
	o expressing certain kinds of data in the target URI is inefficient		o expressing certain kinds of data in the target URI is inefficient
	because of the overhead of encoding that data into a valid URI,		because of the overhead of encoding that data into a valid URI,
	and		and
	skipping to change at page 6, line 41 ¶		skipping to change at page 6, line 41 ¶
	[HTTP-CACHING]).		[HTTP-CACHING]).
	The cache key for a query (see Section 2 of [HTTP-CACHING]) MUST		The cache key for a query (see Section 2 of [HTTP-CACHING]) MUST
	incorporate the request content. When doing so, caches SHOULD first		incorporate the request content. When doing so, caches SHOULD first
	normalize request content to remove semantically insignificant		normalize request content to remove semantically insignificant
	differences, thereby improving cache efficiency, by:		differences, thereby improving cache efficiency, by:
	o Removing content encoding(s)		o Removing content encoding(s)
	o Normalizing based upon knowledge of format conventions, as		o Normalizing based upon knowledge of format conventions, as
	indicated by the any media type suffix in the request's Content-		indicated by any media type suffix in the request's Content-Type
	Type field (e.g., "+json")		field (e.g., "+json")
	o Normalizing based upon knowledge of the semantics of the content		o Normalizing based upon knowledge of the semantics of the content
	itself, as indicated by the request's Content-Type field.		itself, as indicated by the request's Content-Type field.
	Note that any such normalization is performed solely for the purpose		Note that any such normalization is performed solely for the purpose
	of generating a cache key; it does not change the request itself.		of generating a cache key; it does not change the request itself.
			2.5. Range Requests
			The semantics of Range Requests for QUERY are identical to those for
			GET, as defined in Section 14 of [HTTP].
	3. The "Accept-Query" Header Field		3. The "Accept-Query" Header Field
	The "Accept-Query" response header field can be used by a resource to		The "Accept-Query" response header field can be used by a resource to
	directly signal support for the QUERY method while identifying the		directly signal support for the QUERY method while identifying the
	specific query format media type(s) that may be used.		specific query format media type(s) that may be used.
	"Accept-Query" contains a list of media ranges (Section 12.5.1 of		"Accept-Query" contains a list of media ranges (Section 12.5.1 of
	[HTTP]) using "Structured Fields" syntax ([STRUCTURED-FIELDS]).		[HTTP]) using "Structured Fields" syntax ([STRUCTURED-FIELDS]).
	Media ranges are represented by a List Structured Header Field of		Media ranges are represented by a List Structured Header Field of
	either Tokens or Strings, containing the media range value without		either Tokens or Strings, containing the media range value without
	skipping to change at page 8, line 16 ¶		skipping to change at page 8, line 21 ¶
	the URI (e.g., in the query section). This is preferred in some		the URI (e.g., in the query section). This is preferred in some
	cases, as the URI is more likely to be logged or otherwise processed		cases, as the URI is more likely to be logged or otherwise processed
	by intermediaries than the request content. If a server creates a		by intermediaries than the request content. If a server creates a
	temporary resource to represent the results of a QUERY request (e.g.,		temporary resource to represent the results of a QUERY request (e.g.,
	for use in the Location or Content-Location field) and the request		for use in the Location or Content-Location field) and the request
	contains sensitive information that cannot be logged, then the URI of		contains sensitive information that cannot be logged, then the URI of
	this resource SHOULD be chosen such that it does not include any		this resource SHOULD be chosen such that it does not include any
	sensitive portions of the original request content.		sensitive portions of the original request content.
	Caches that normalize QUERY content incorrectly or in ways that are		Caches that normalize QUERY content incorrectly or in ways that are
	significantly different than how the resource processes the content		significantly different from how the resource processes the content
	can return the incorrect response if normalization results in a false		can return the incorrect response if normalization results in a false
	positive.		positive.
	A QUERY request from user agents implementing CORS (Cross-Origin		A QUERY request from user agents implementing CORS (Cross-Origin
	Resource Sharing) will require a "preflight" request, as QUERY does		Resource Sharing) will require a "preflight" request, as QUERY does
	not belong to the set of CORS-safelisted methods (see "Methods		not belong to the set of CORS-safelisted methods (see "Methods
	(https://fetch.spec.whatwg.org/#methods)" in [FETCH]).		(https://fetch.spec.whatwg.org/#methods)" in [FETCH]).
	5. IANA Considerations		5. IANA Considerations
	skipping to change at page 15, line 26 ¶		skipping to change at page 15, line 26 ¶
	o Reference HTTP spec for terminology (<https://github.com/httpwg/		o Reference HTTP spec for terminology (<https://github.com/httpwg/
	http-extensions/issues/2953>)		http-extensions/issues/2953>)
	o Moved BCP14 related text into subsection		o Moved BCP14 related text into subsection
	(<https://github.com/httpwg/http-extensions/issues/2954>)		(<https://github.com/httpwg/http-extensions/issues/2954>)
	o Move examples into index (<https://github.com/httpwg/http-		o Move examples into index (<https://github.com/httpwg/http-
	extensions/issues/2957>)		extensions/issues/2957>)
			B.8. Since draft-ietf-httpbis-safe-method-w-body-07
			o Discuss Range Requests (<https://github.com/httpwg/http-
			extensions/issues/2979>)
	Authors' Addresses		Authors' Addresses
	Julian Reschke		Julian Reschke
	greenbytes GmbH		greenbytes GmbH
	Hafenweg 16		Hafenweg 16
	48155 Münster		48155 Münster
	Germany		Germany
	Email: julian.reschke@greenbytes.de		Email: julian.reschke@greenbytes.de
	URI: https://greenbytes.de/tech/webdav/		URI: https://greenbytes.de/tech/webdav/
End of changes. 14 change blocks.
	13 lines changed or deleted		24 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/