draft-ietf-httpbis-safe-method-w-body-12.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 J.M. Snell		Intended status: Standards Track J.M. Snell
	Expires: April 2, 2026 Cloudflare		Expires: May 10, 2026 Cloudflare
	M. Bishop		M. Bishop
	Akamai		Akamai
	September 29, 2025		November 6, 2025
	The HTTP QUERY Method		The HTTP QUERY Method
	draft-ietf-httpbis-safe-method-w-body-12		draft-ietf-httpbis-safe-method-w-body-latest
	Abstract		Abstract
	This specification defines the QUERY method for HTTP. A QUERY		This specification defines the QUERY method for HTTP. A QUERY
	requests that the request target process the enclosed content in a		requests that the request target process the enclosed content in a
	safe/idempotent manner and then respond with the result of that		safe/idempotent manner and then respond with the result of that
	processing. This is similar to POST requests but can be		processing. This is similar to POST requests but can be
	automatically repeated or restarted without concern for partial state		automatically repeated or restarted without concern for partial state
	changes.		changes.
	skipping to change at page 1, line 35 ¶		skipping to change at page 1, line 35 ¶
	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.12.		The changes in this draft are summarized in Appendix B.13.
	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 April 2, 2026.		This Internet-Draft will expire on May 10, 2026.
	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 (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
	skipping to change at page 3, line 22 ¶		skipping to change at page 3, line 22 ¶
	B.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 26		B.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 26
	B.4. Since draft-ietf-httpbis-safe-method-w-body-03 . . . . . 26		B.4. Since draft-ietf-httpbis-safe-method-w-body-03 . . . . . 26
	B.5. Since draft-ietf-httpbis-safe-method-w-body-04 . . . . . 26		B.5. Since draft-ietf-httpbis-safe-method-w-body-04 . . . . . 26
	B.6. Since draft-ietf-httpbis-safe-method-w-body-05 . . . . . 26		B.6. Since draft-ietf-httpbis-safe-method-w-body-05 . . . . . 26
	B.7. Since draft-ietf-httpbis-safe-method-w-body-06 . . . . . 27		B.7. Since draft-ietf-httpbis-safe-method-w-body-06 . . . . . 27
	B.8. Since draft-ietf-httpbis-safe-method-w-body-07 . . . . . 28		B.8. Since draft-ietf-httpbis-safe-method-w-body-07 . . . . . 28
	B.9. Since draft-ietf-httpbis-safe-method-w-body-08 . . . . . 28		B.9. Since draft-ietf-httpbis-safe-method-w-body-08 . . . . . 28
	B.10. Since draft-ietf-httpbis-safe-method-w-body-09 . . . . . 28		B.10. Since draft-ietf-httpbis-safe-method-w-body-09 . . . . . 28
	B.11. Since draft-ietf-httpbis-safe-method-w-body-10 . . . . . 28		B.11. Since draft-ietf-httpbis-safe-method-w-body-10 . . . . . 28
	B.12. Since draft-ietf-httpbis-safe-method-w-body-11 . . . . . 29		B.12. Since draft-ietf-httpbis-safe-method-w-body-11 . . . . . 29
			B.13. Since draft-ietf-httpbis-safe-method-w-body-12 . . . . . 29
	Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 30		Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 30
	Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 30		Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 30
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30
	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 (Section 9.2 of [HTTP])		of making a safe, idempotent request (Section 9.2 of [HTTP]) that
	containing content that describes how the request is to be processed		encloses a representation describing how the request is to be
	by the target resource.		processed by the target resource.
	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. A common query		too voluminous to be encoded into the request's URI. A common query
	pattern is:		pattern is:
	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, when the data conveyed is too voluminous to be encoded in		However, when the data conveyed is too voluminous to be encoded in
	the request's URI, this pattern becomes problematic:		the request's URI, this pattern becomes problematic:
	skipping to change at page 4, line 25 ¶		skipping to change at page 4, line 25 ¶
	component.		component.
	A typical use of HTTP POST for requesting a query is:		A typical use of HTTP POST for requesting a query is:
	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 fact that it is not readily		In this variation, however, it is not readily apparent -- absent
	apparent -- absent specific knowledge of the resource and server to		specific knowledge of the resource and server to which the request is
	which the request is being sent -- that a safe, idempotent query is		being sent -- that a safe, idempotent query is being performed.
	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, with the example above being expressed as:		use of GET and POST, with the example above being expressed as:
	QUERY /feed HTTP/1.1		QUERY /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
	skipping to change at page 5, line 49 ¶		skipping to change at page 5, line 49 ¶
	"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
	GET method, which requests a representation of the resource		GET method, which requests a representation of the resource
	identified by the target URI (as defined by Section 7.1 of [HTTP]),		identified by the target URI (as defined by Section 7.1 of [HTTP]),
	the QUERY method is used to ask the target resource to perform a		the QUERY method is used to ask the target resource to perform a
	query operation within the scope of that target resource. The query		query operation within the scope of that target resource.
	operation is described by the request content. The origin server
	determines the scope of the operation based on the target resource.		The content of the request and its media type define the query. The
			origin server determines the scope of the operation based on the
			target resource.
	The content of the request and its media type define the query.
	Servers MUST fail the request if the Content-Type request field		Servers MUST fail the request if the Content-Type request field
	([HTTP], Section 8.3) is missing or is inconsistent with the request		([HTTP], Section 8.3) is missing or is inconsistent with the request
	content.		content.
	As for all HTTP methods, the target URI's query part takes part in		As for all HTTP methods, the target URI's query part takes part in
	identifying the resource being queried. Whether and how it directly		identifying the resource being queried. Whether and how it directly
	affects the result of the query is specific to the resource and out		affects the result of the query is specific to the resource and out
	of scope for this specification.		of scope for this specification.
	QUERY requests are safe with regard to the target resource ([HTTP],		QUERY requests are safe with regard to the target resource ([HTTP],
	skipping to change at page 6, line 41 ¶		skipping to change at page 6, line 44 ¶
	enclosed as the response content.		enclosed as the response content.
	2.1. Media Types and Content Negotiation		2.1. Media Types and Content Negotiation
	The semantics of a QUERY request depends both on the request content		The semantics of a QUERY request depends both on the request content
	and the associated metadata, such as the Media Type ([HTTP],		and the associated metadata, such as the Media Type ([HTTP],
	Section 8.3.1). In general, any problem with requests where content		Section 8.3.1). In general, any problem with requests where content
	and metadata are inconsistent MUST be rejected with a 4xx (Client		and metadata are inconsistent MUST be rejected with a 4xx (Client
	Error) response ([HTTP], Section 15.5).		Error) response ([HTTP], Section 15.5).
	The list below describe various cases of failures and recommends		The list below describes various cases of failures and recommends
	specific status codes:		specific status codes:
	o A request lacking media type information by definition is		o A request lacking media type information by definition is
	incorrect and needs to fail with a 4xx status code such as 400		incorrect and needs to fail with a 4xx status code such as 400
	(Client Error).		(Client Error).
	o If a media type is specified, but not supported by the resource, a		o If a media type is specified, but not supported by the resource, a
	415 (Unsupported Media Type) is appropriate. This specifically		415 (Unsupported Media Type) is appropriate. This specifically
	includes the case where the media type is known in principle, but		includes the case where the media type is known in principle, but
	lacks semantics specific to a QUERY to the target resource. In		lacks semantics specific to a QUERY to the target resource. In
	both cases, the Accept-Query response field (Section 3) can be		both cases, the Accept-Query response field (Section 3) can be
	used to inform the client of media types which are supported.		used to inform the client of media types which are supported.
	o If a media type is specified, but is inconsistent with the actual		o If a media type is specified, but is inconsistent with the actual
	request content, a 400 (Bad Request) can be returned. That is, a		request content, a 400 (Bad Request) can be returned. That is, a
	server is not allowed to infer a media type from the request		server is not allowed to infer a media type from the request
	content and then override a missing or "erroneous" value ("content		content and then override a missing or "erroneous" value ("content
	sniffing").		sniffing").
	o If the media type is specified, is understood, and the content is		o If the media type is specified, is understood, and the content is
	indeed consistent with the type, but the query can not be		indeed consistent with the type, but the query cannot be processed
	processed due to the actual contents of the query, the status 422		due to the actual contents of the query, the status 422
	(Unprocessable Content) can be used. An example would be a		(Unprocessable Content) can be used. An example would be a
	syntactically correct SQL query that identifies a non-existent		syntactically correct SQL query that identifies a non-existent
	table.		table.
	o Finally, if the client requests a specific response media type		o Finally, if the client requests a specific response media type
	using the Accept field ([HTTP], Section 12.5.1) which is not		using the Accept field ([HTTP], Section 12.5.1) which is not
	supported by the resource, a status code of 406 (Not Acceptable)		supported by the resource, a status code of 406 (Not Acceptable)
	is appropriate.		is appropriate.
	2.2. Equivalent Resource		2.2. Equivalent Resource
	skipping to change at page 8, line 37 ¶		skipping to change at page 8, line 37 ¶
	submitted content.		submitted content.
	See Appendix A.4.2 for an example.		See Appendix A.4.2 for an example.
	2.5. Redirection		2.5. Redirection
	In some cases, the server may choose to respond indirectly to the		In some cases, the server may choose to respond indirectly to the
	QUERY request by redirecting the user agent to a different URI (see		QUERY request by redirecting the user agent to a different URI (see
	Section 15.4 of [HTTP]).		Section 15.4 of [HTTP]).
	A response with either of the status codes 301 (Moved Permanently,		A response with either status codes 301 (Moved Permanently, [HTTP],
	[HTTP], Section 15.4.2) or 308 (Permanent Redirect, [HTTP],		Section 15.4.2) or 308 (Permanent Redirect, [HTTP], Section 15.4.9)
	Section 15.4.9) indicates that the target resource has permanently		indicates that the target resource has permanently moved to a
	moved to a different URI referenced by the Location response field		different URI referenced by the Location response field ([HTTP],
	([HTTP], Section 10.2.2). Likewise, a response with either 302		Section 10.2.2). Likewise, a response with either status codes 302
	(Found, [HTTP], Section 15.4.3 or 307 (Temporary Redirect, [HTTP],		(Found, [HTTP], Section 15.4.3) or 307 (Temporary Redirect, [HTTP],
	Section 15.4.8) indicates that the target resource has temporarily		Section 15.4.8) indicates that the target resource has temporarily
	moved. In all four cases, the server is suggesting that the user		moved. In all four cases, the server is suggesting that the user
	agent can accomplish its original QUERY request by sending a similar		agent can accomplish its original QUERY request by sending a similar
	QUERY request to the new target URI referenced by Location.		QUERY request to the new target URI referenced by Location.
	Note that the exceptions for redirecting a POST as a GET request		Note that the exceptions for redirecting a POST as a GET request
	after a 301 or 302 response do not apply to QUERY requests.		after a 301 or 302 response do not apply to QUERY requests.
	A response to QUERY with the status code 303 (See Other,		A response to QUERY with the status code 303 (See Other,
	Section 15.4.4 of [HTTP]) indicates that the original query can be		Section 15.4.4 of [HTTP]) indicates that the original query can be
	skipping to change at page 9, line 28 ¶		skipping to change at page 9, line 28 ¶
	A conditional QUERY requests that that selected representation (i.e.,		A conditional QUERY requests that that selected representation (i.e.,
	the query results, after any content negotiation) be returned in the		the query results, after any content negotiation) be returned in the
	response only under the circumstances described by the conditional		response only under the circumstances described by the conditional
	header field(s), as defined in Section 13 of [HTTP].		header field(s), as defined in Section 13 of [HTTP].
	See Appendix A.5 for examples.		See Appendix A.5 for examples.
	2.7. Caching		2.7. 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 [HTTP-CACHING].
	[HTTP-CACHING]).
	The cache key for a QUERY request (see Section 2 of [HTTP-CACHING])		The cache key for a QUERY request (see Section 2 of [HTTP-CACHING])
	MUST incorporate the request content (Section 6 of [HTTP-CACHING])		MUST incorporate the request content (Section 6 of [HTTP-CACHING])
	and related metadata (Section 8 of [HTTP-CACHING]).		and related metadata (Section 8 of [HTTP-CACHING]).
	Caches MAY remove semantically insignificant differences first,		To improve cache efficiency, caches MAY remove semantically
	thereby improving cache efficiency.		insignificant differences first. For instance, by:
	For instance, by
	o removing content encoding(s) (Section 8.4 of [HTTP]).		o removing content encoding(s) (Section 8.4 of [HTTP]).
	o normalizing based upon knowledge of format conventions, as		o normalizing based upon knowledge of format conventions, as
	indicated by any media subtype suffix in the request's Content-		indicated by any media subtype suffix in the request's Content-
	Type field (e.g., "+json", see Section 4.2.8 of [RFC6838]).		Type field (e.g., "+json", see Section 4.2.8 of [RFC6838]).
	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.
	skipping to change at page 19, line 9 ¶		skipping to change at page 19, line 9 ¶
	This is similar to including Location on a direct response, except		This is similar to including Location on a direct response, except
	that no result for the query is returned. This allows the server to		that no result for the query is returned. This allows the server to
	only generate or reuse an alternative resource. This resource could		only generate or reuse an alternative resource. This resource could
	then be used as shown in Appendix A.4.2.		then be used as shown in Appendix A.4.2.
	A.5. Conditional Requests		A.5. Conditional Requests
	Consider a resource implementing QUERY that supports "application/		Consider a resource implementing QUERY that supports "application/
	sql" and "application/xslt+xml" ([XSLT]) as request media types, and		sql" and "application/xslt+xml" ([XSLT]) as request media types, and
	which can generate responses as "text/csv" . The data set being		which can generate responses as "text/csv". The data set being
	queried contains RFC document information, and the query returns		queried contains RFC document information, and the query returns
	information grouped by decade:		information grouped by decade:
	QUERY /rfc-index.xml HTTP/1.1		QUERY /rfc-index.xml HTTP/1.1
	Host: example.org		Host: example.org
	Date: Sun, 7 Sep 2025, 00:00:00 GMT		Date: Sun, 7 Sep 2025, 00:00:00 GMT
	Content-Type: application/xslt+xml		Content-Type: application/xslt+xml
	Accept: text/csv		Accept: text/csv
	...Query content using XSLT...		...Query content using XSLT...
	skipping to change at page 30, line 5 ¶		skipping to change at page 29, line 50 ¶
	o Consistent Table Captions (<https://github.com/httpwg/http-		o Consistent Table Captions (<https://github.com/httpwg/http-
	extensions/issues/3134>)		extensions/issues/3134>)
	o Define "Equivalent Resource", update description of Conditional		o Define "Equivalent Resource", update description of Conditional
	Requests, add examples (<https://github.com/httpwg/http-		Requests, add examples (<https://github.com/httpwg/http-
	extensions/issues/3137>)		extensions/issues/3137>)
	o Extend discussion of Range Requests (<https://github.com/httpwg/		o Extend discussion of Range Requests (<https://github.com/httpwg/
	http-extensions/issues/3151>)		http-extensions/issues/3151>)
			B.13. Since draft-ietf-httpbis-safe-method-w-body-12
			o Ack Asbjørn Ulsberg (<https://github.com/httpwg/http-extensions/
			issues/3299>)
			o LC feedback from Rahul Gupta (<https://github.com/httpwg/http-
			extensions/issues/3315>)
	Acknowledgements		Acknowledgements
	We thank all members of the HTTP Working Group for ideas, reviews,		We thank all members of the HTTP Working Group for ideas, reviews,
	and feedback.		and feedback.
	The following individuals deserve special recognition: Carsten		The following individuals deserve special recognition: Carsten
	Bormann, Mark Nottingham, Martin Thomson, Michael Thornburgh, Roberto		Bormann, Mark Nottingham, Martin Thomson, Michael Thornburgh, Roberto
	Polli, Roy Fielding, and Will Hawkins.		Polli, Roy Fielding, and Will Hawkins.
	Contributors		Contributors
	Ashok Malhotra participated in early discussions leading to this		Ashok Malhotra participated in early discussions leading to this
	specification:		specification:
	Ashok Malhotra		Ashok Malhotra
	Email: malhotrasahib@gmail.com		Email: malhotrasahib@gmail.com
			Discussion on the this HTTP method was reopened by Asbjørn Ulsberg
			during the HTTP Workshop in 2019:
			Asbjørn Ulsberg
			Email: asbjorn@ulsberg.no
			URI: https://asbjor.nu/
	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. 18 change blocks.
	32 lines changed or deleted		44 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/