draft-ietf-httpbis-safe-method-w-body-02.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: May 13, 2022		Expires: December 23, 2022
	J.M. Snell		J.M. Snell
	November 9, 2021		June 21, 2022
	The HTTP QUERY Method		The HTTP QUERY Method
	draft-ietf-httpbis-safe-method-w-body-02		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/safe-method-		<https://github.com/httpwg/http-extensions/labels/safe-method-
	w-body>.		w-body>.
	The changes in this draft are summarized in Appendix A.2.		The changes in this draft are summarized in Appendix A.3.
	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 May 13, 2022.		This Internet-Draft will expire on December 23, 2022.
	Copyright Notice		Copyright Notice
	Copyright (c) 2021 IETF Trust and the persons identified as the		Copyright (c) 2022 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 32 ¶		skipping to change at page 2, line 32 ¶
	2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
	2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 4		2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 5		3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 5
	4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5		4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5
	4.1. Simple QUERY with a Direct Response . . . . . . . . . . . 5		4.1. Simple QUERY with a Direct Response . . . . . . . . . . . 5
	4.2. Simple QUERY with indirect response (303 See Other) . . . 6		4.2. Simple QUERY with indirect response (303 See Other) . . . 6
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 7		5. Security Considerations . . . . . . . . . . . . . . . . . . . 7
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
	7. Normative References . . . . . . . . . . . . . . . . . . . . 7		7. Normative References . . . . . . . . . . . . . . . . . . . . 7
	Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 7		Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 7
	A.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 8		A.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 7
	A.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 8		A.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 8
			A.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 8
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8
	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,
	while this is an common and interoperable query:		while this is an common and interoperable query:
	skipping to change at page 3, line 19 ¶		skipping to change at page 3, line 19 ¶
	because it needs to be encoded to be a valid URI.		because it needs to be encoded to be a valid URI.
	Encoding query parameters directly into the request URI also		Encoding query parameters directly into the request URI also
	effectively casts every possible combination of query inputs as		effectively casts every possible combination of query inputs as
	distinct resources. Depending on the application, that may not be		distinct resources. Depending on the application, that may not be
	desirable.		desirable.
	As an alternative to using GET, many implementations make use of the		As an alternative to using GET, many implementations make use of the
	HTTP POST method to perform queries, as illustrated in the example		HTTP POST method to perform queries, as illustrated in the example
	below. In this case, the input parameters to the search operation		below. In this case, the input parameters to the search operation
	are passed along within the request payload as opposed to using the		are passed along within the request content as opposed to using the
	request URI.		request URI.
	A typical use of HTTP POST for requesting a search		A typical use of HTTP POST for requesting a search
	POST /feed HTTP/1.1		POST /feed HTTP/1.1
	Host: example.org		Host: example.org
	Content-Type: application/x-www-form-urlencoded		Content-Type: application/x-www-form-urlencoded
	q=foo&limit=10&sort=-published		q=foo&limit=10&sort=-published
	This variation, however, suffers from the same basic limitation as		This variation, however, suffers from the same basic limitation as
	GET in that it is not readily apparent -- absent specific knowledge		GET in that it is not readily apparent -- absent specific knowledge
	of the resource and server to which the request is being sent -- that		of the resource and server to which the request is being sent -- that
	a safe, idempotent query is being performed.		a safe, idempotent query is being performed.
	The QUERY method provides a solution that spans the gap between the		The QUERY method provides a solution that spans the gap between the
	use of GET and POST. As with POST, the input to the query operation		use of GET and POST. As with POST, the input to the query operation
	is passed along within the payload of the request rather than as part		is passed along within the content of the request rather than as part
	of the request URI. Unlike POST, however, the method is explicitly		of the request URI. Unlike POST, however, the method is explicitly
	safe and idempotent, allowing functions like caching and automatic		safe and idempotent, allowing functions like caching and automatic
	retries to operate.		retries to operate.
	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. QUERY		2. QUERY
	The QUERY method is used to initiate a server-side query. Unlike the		The QUERY method is used to initiate a server-side query. Unlike the
	HTTP GET method, which requests that a server return a representation		HTTP GET method, which requests that a server return a representation
	of the resource identified by the target URI (as defined by		of the resource identified by the target URI (as defined by
	Section 7.1 of [RFCHTTP]), the QUERY method is used to ask the server		Section 7.1 of [HTTP]), the QUERY method is used to ask the server to
	to perform a query operation (described by the request payload) over		perform a query operation (described by the request content) over
	some set of data scoped to the effective request URI. The payload		some set of data scoped to the effective request URI. The content
	returned in response to a QUERY cannot be assumed to be a		returned in response to a QUERY cannot be assumed to be a
	representation of the resource identified by the effective request		representation of the resource identified by the effective request
	URI.		URI.
	The body payload of the request defines the query. Implementations		The content of the request defines the query. Implementations MAY
	MAY use a request body of any content type with the QUERY method,		use a request content of any media type with the QUERY method,
	provided that it has appropriate query semantics.		provided that it has appropriate query semantics.
	QUERY requests are both safe and idempotent with regards to the		QUERY requests are both safe and idempotent with regards to the
	resource identified by the request URI. That is, QUERY requests do		resource identified by the request URI. That is, QUERY requests do
	not alter the state of the targeted resource. However, while		not alter the state of the targeted resource. However, while
	processing a QUERY request, a server can be expected to allocate		processing a QUERY request, a server can be expected to allocate
	computing and memory resources or even create additional HTTP		computing and memory resources or even create additional HTTP
	resources through which the response can be retrieved.		resources through which the response can be retrieved.
	A successful response to a QUERY request is expected to provide some		A successful response to a QUERY request is expected to provide some
	skipping to change at page 4, line 41 ¶		skipping to change at page 4, line 41 ¶
	represented by a 204 No Content response. If the response includes		represented by a 204 No Content response. If the response includes
	content, it is expected to describe the results of the operation. In		content, it is expected to describe the results of the operation. In
	some cases, the server may choose to respond indirectly to the QUERY		some cases, the server may choose to respond indirectly to the QUERY
	request by returning a 3xx Redirection with a Location header field		request by returning a 3xx Redirection with a Location header field
	specifying an alternate Request URI from which the results can be		specifying an alternate Request URI from which the results can be
	retrieved using an HTTP GET request. Various non-normative examples		retrieved using an HTTP GET request. Various non-normative examples
	of successful QUERY responses are illustrated in Section 4.		of successful QUERY responses are illustrated in Section 4.
	The semantics of the QUERY method change to a "conditional QUERY" if		The semantics of the QUERY method change to a "conditional QUERY" if
	the request message includes an If-Modified-Since, If-Unmodified-		the request message includes an If-Modified-Since, If-Unmodified-
	Since, If-Match, If-None-Match, or If-Range header field ([RFCHTTP],		Since, If-Match, If-None-Match, or If-Range header field ([HTTP],
	Section 13). A conditional QUERY requests that the query be		Section 13). A conditional QUERY requests that the query be
	performed only under the circumstances described by the conditional		performed only under the circumstances described by the conditional
	header field(s). It is important to note, however, that such		header field(s). It is important to note, however, that such
	conditions are evaluated against the state of the target resource		conditions are evaluated against the state of the target resource
	itself as opposed to the collected results of the search operation.		itself as opposed to the collected results of the search operation.
	2.1. Caching		2.1. Caching
	The response to a QUERY method is cacheable; a cache MAY use it to		The response to a QUERY method is cacheable; a cache MAY use it to
	satisfy subsequent QUERY requests as per Section 4 of		satisfy subsequent QUERY requests as per Section 4 of
	skipping to change at page 5, line 32 ¶		skipping to change at page 5, line 32 ¶
	3. The "Accept-Query" Header Field		3. The "Accept-Query" Header Field
	The "Accept-Query" response header field MAY be used by a server to		The "Accept-Query" response header field MAY be used by a server 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 = 1#media-type		Accept-Query = 1#media-type
	The Accept-Query header field specifies a comma-separated listing of		The Accept-Query header field specifies a comma-separated listing of
	media types (with optional parameters) as defined by Section 8.3.1 of		media types (with optional parameters) as defined by Section 8.3.1 of
	[RFCHTTP].		[HTTP].
	The order of types listed by the Accept-Query header field is		The order of types listed by the Accept-Query header field is not
	insignificant.		significant.
	4. Examples		4. Examples
	The non-normative examples in this section make use of a simple,		The non-normative examples in this section make use of a simple,
	hypothetical plain-text based query syntax based on SQL with results		hypothetical plain-text based query syntax based on SQL with results
	returned as comma-separated values. This is done for illustration		returned as comma-separated values. This is done for illustration
	purposes only. Implementations are free to use any format they wish		purposes only. Implementations are free to use any format they wish
	on both the request and response.		on both the request and response.
	4.1. Simple QUERY with a Direct Response		4.1. Simple QUERY with a Direct Response
	skipping to change at page 7, line 8 ¶		skipping to change at page 7, line 8 ¶
	Content-Type: text/csv		Content-Type: text/csv
	surname, givenname, email		surname, givenname, email
	Smith, John, john.smith@example.org		Smith, John, john.smith@example.org
	Jones, Sally, sally.jones@example.com		Jones, Sally, sally.jones@example.com
	Dubois, Camille, camille.dubois@example.net		Dubois, Camille, camille.dubois@example.net
	5. Security Considerations		5. Security Considerations
	The QUERY method is subject to the same general security		The QUERY method is subject to the same general security
	considerations as all HTTP methods as described in [RFCHTTP].		considerations as all HTTP methods as described in [HTTP].
	6. IANA Considerations		6. IANA Considerations
	IANA is requested to add QUERY method in the permanent registry at		IANA is requested to add QUERY method in the permanent registry at
	<http://www.iana.org/assignments/http-methods> (see Section 16.1.1 of		<http://www.iana.org/assignments/http-methods> (see Section 16.1.1 of
	[RFCHTTP]).		[HTTP]).
	+-------------+------+------------+---------------+		+-------------+------+------------+---------------+
	| Method Name | Safe | Idempotent | Specification |		| Method Name | Safe | Idempotent | Specification |
	+-------------+------+------------+---------------+		+-------------+------+------------+---------------+
	| QUERY | Yes | Yes | Section 2 |		| QUERY | Yes | Yes | Section 2 |
	+-------------+------+------------+---------------+		+-------------+------+------------+---------------+
	Table 1		Table 1
	7. Normative References		7. Normative References
			[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
			Ed., "HTTP Semantics", STD 97, RFC 9110,
			DOI 10.17487/RFC9110, June 2022,
			<https://www.rfc-editor.org/info/rfc9110>.
	[HTTP-CACHING]		[HTTP-CACHING]
	Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,		Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
	Ed., "HTTP Semantics", Work in Progress, Internet-Draft,		Ed., "HTTP Caching", STD 98, RFC 9111,
	draft-ietf-httpbis-cache-19, September 10, 2021,		DOI 10.17487/RFC9111, June 2022,
	<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-		<https://www.rfc-editor.org/info/rfc9111>.
	cache-19>.
	[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>.
	[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>.
	[RFCHTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
	Ed., "HTTP Semantics", Work in Progress, Internet-Draft,
	draft-ietf-httpbis-semantics-19, September 10, 2021,
	<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis-
	semantics-19>.
	Appendix A. Change Log		Appendix A. Change Log
	This section is to be removed before publishing as an RFC.		This section is to be removed before publishing as an RFC.
	A.1. Since draft-ietf-httpbis-safe-method-w-body-00		A.1. Since draft-ietf-httpbis-safe-method-w-body-00
	o Use "example/query" media type instead of undefined "text/query"		o Use "example/query" media type instead of undefined "text/query"
	(<https://github.com/httpwg/http-extensions/issues/1450>)		(<https://github.com/httpwg/http-extensions/issues/1450>)
	o In Section 3, adjust the grammar to just define the field value		o In Section 3, adjust the grammar to just define the field value
	(<https://github.com/httpwg/http-extensions/issues/1470>)		(<https://github.com/httpwg/http-extensions/issues/1470>)
	o Update to latest HTTP core spec, and adjust terminology		o Update to latest HTTP core spec, and adjust terminology
	accordingly (<https://github.com/httpwg/http-extensions/		accordingly (<https://github.com/httpwg/http-extensions/
	issues/1473>)		issues/1473>)
	o Reference RFC 8174 and markup bcp14 terms		o Reference RFC 8174 and markup bcp14 terms
	(<https://github.com/httpwg/http-extensions/issues/1497>)		(<https://github.com/httpwg/http-extensions/issues/1497>)
	o Update HTTP reference (<https://github.com/httpwg/http-extensions/		o Update HTTP reference (<https://github.com/httpwg/http-extensions/
	issues/1524>)		issues/1524>)
	o Relax restriction of generic XML media type in request body		o Relax restriction of generic XML media type in request content
	(<https://github.com/httpwg/http-extensions/issues/1535>)		(<https://github.com/httpwg/http-extensions/issues/1535>)
	A.2. Since draft-ietf-httpbis-safe-method-w-body-01		A.2. Since draft-ietf-httpbis-safe-method-w-body-01
	o Add minimal description of cacheability		o Add minimal description of cacheability
	(<https://github.com/httpwg/http-extensions/issues/1552>)		(<https://github.com/httpwg/http-extensions/issues/1552>)
	o Use "QUERY" as method name (<https://github.com/httpwg/http-		o Use "QUERY" as method name (<https://github.com/httpwg/http-
	extensions/issues/1614>)		extensions/issues/1614>)
	o Update HTTP reference (<https://github.com/httpwg/http-extensions/		o Update HTTP reference (<https://github.com/httpwg/http-extensions/
	issues/1669>)		issues/1669>)
			A.3. Since draft-ietf-httpbis-safe-method-w-body-02
			o In Section 3, slightly rephrase statement about significance of
			ordering (<https://github.com/httpwg/http-extensions/issues/1896>)
			o Throughout: use "content" instead of "payload" or "body"
			(<https://github.com/httpwg/http-extensions/issues/1915>)
			o Updated references (<https://github.com/httpwg/http-extensions/
			issues/2157>)
	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. 23 change blocks.
	32 lines changed or deleted		41 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/