| HTTP Working Group | J. Reschke |
| Internet-Draft | greenbytes |
| Intended status: Standards Track | J. Snell |
| Expires: February 27, 2026 | Cloudflare |
| M. Bishop | |
| Akamai | |
| August 26, 2025 |
This specification defines the QUERY method for HTTP. A QUERY requests that the request target process the enclosed content in a safe/idempotent manner and then respond with the result of that processing. This is similar to POST requests but can be automatically repeated or restarted without concern for partial state changes.¶
This note is to be removed before publishing as an RFC.¶
Discussion of this draft takes place on the HTTP working group mailing list (ietf-http-wg@w3.org), which is archived at https://lists.w3.org/Archives/Public/ietf-http-wg/.¶
Working Group information can be found at https://httpwg.org/; source code and issues list for this draft can be found at https://github.com/httpwg/http-extensions/labels/query-method.¶
The changes in this draft are summarized in Appendix B.12.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress”.¶
This Internet-Draft will expire on February 27, 2026.¶
Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
This specification defines the HTTP QUERY request method as a means of making a safe, idempotent request (Section 9.2 of [HTTP]) containing content that describes how the request is to be processed by the target resource.¶
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 pattern is:¶
GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 Host: example.org
However, when the data conveyed is too voluminous to be encoded in the request's URI, this pattern becomes problematic:¶
As an alternative to using GET, many implementations make use of the HTTP POST method to perform queries, as illustrated in the example below. In this case, the input to the query operation is passed as the request content as opposed to using the request URI's query component.¶
A typical use of HTTP POST for requesting a query is:¶
POST /feed HTTP/1.1 Host: example.org Content-Type: application/x-www-form-urlencoded q=foo&limit=10&sort=-published
This variation, however, suffers from the fact that it is not readily apparent -- absent specific knowledge of the resource and server to which the request is being sent -- that a safe, idempotent query is being performed.¶
The QUERY method provides a solution that spans the gap between the use of GET and POST, with the example above being expressed as:¶
QUERY /feed HTTP/1.1 Host: example.org Content-Type: application/x-www-form-urlencoded q=foo&limit=10&sort=-published
As with POST, the input to the query operation is passed as the content of the request rather than as part of the request URI. Unlike POST, however, the method is explicitly safe and idempotent, allowing functions like caching and automatic retries to operate.¶
Recognizing the design principle that any important resource ought to be identified by a URI, this specification describes how a server can assign URIs to both the query itself or a specific query result, for later use in a GET request.¶
Summarizing:¶
| GET | QUERY | POST | |
|---|---|---|---|
| Safe | yes | yes | potentially no |
| Idempotent | yes | yes | potentially no |
| URI for query itself | yes (by definition) | optional (Location response field) | no |
| URI for query result | optional (Content-Location response field) | optional (Content-Location response field) | optional (Content-Location response field) |
| Cacheable | yes | yes | yes, but only for future GET or HEAD requests |
| Content (body) | "no defined semantics" | expected (semantics per target resource) | expected (semantics per target resource) |
Furthermore, it uses the terms URI query parameter for parameters in the query component of a URI (Section 4.2.2 of [HTTP]) and query content for the request content (Section 6.4 of [HTTP]) of a QUERY request.¶
The QUERY method is used to initiate a server-side query. Unlike the GET method, which requests a representation of the resource 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 query operation within the scope of that target resource. The query 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. Servers MUST fail the request if the Content-Type request field ([HTTP], Section 8.3) is missing or is inconsistent with the request content.¶
As for all HTTP methods, the target URI's query part takes part in identifying the resource being queried. Whether and how it directly affects the result of the query is specific to the resource and out of scope for this specification.¶
QUERY requests are safe with regard to the target resource ([HTTP], Section 9.2.1) -- that is, the client does not request or expect any change to the state of the target resource. This does not prevent the server from creating additional HTTP resources through which additional information can be retrieved (see Sections 2.2 and 2.3).¶
Furthermore, QUERY requests are idempotent ([HTTP], Section 9.2.2) -- they can be retried or repeated when needed, for instance after a connection failure.¶
As per Section 15.3 of [HTTP], a 2xx (Successful) response code signals that the request was successfully received, understood, and accepted.¶
In particular, a 200 (OK) response indicates that the query was successfully processed and the results of that processing are enclosed as the response content.¶
The semantics of a QUERY request depends both on the request content and the associated metadata, such as the Media Type ([HTTP], Section 8.3.1). In general, any problem with requests where content and metadata are inconsistent MUST be rejected with a 4xx (Client Error) response ([HTTP], Section 15.5).¶
The list below describe various cases of failures and recommends specific status codes:¶
A successful response (2xx, Section 15.3 of [HTTP]) can include a Content-Location header field containing an identifier for a resource corresponding to the results of the operation; see Section 8.7 of [HTTP] for details. This represents a claim from the server that a client can send a GET request for the indicated URI to retrieve the results of the query operation just performed. The indicated resource might be temporary.¶
See Appendix A.4.1 for an example.¶
A server can create or locate a resource that identifies the query operation for future use. If the server does so, the URI of the resource can be included in the Location header field of the 2xx response (see Section 10.2.2 of [HTTP]). This represents a claim that a client can send a GET request to the indicated URI to repeat the query operation just performed without resending the query content. This resource might be temporary; if a future request fails, the client can retry using the original QUERY resource and the previously submitted content.¶
See Appendix A.4.2 for an example.¶
In some cases, the server may choose to respond indirectly to the QUERY request by redirecting the user agent to a different URI (see Section 15.4 of [HTTP]).¶
A response with either of the status codes 301 (Moved Permanently, [HTTP], Section 15.4.2) or 308 (Permanent Redirect, [HTTP], Section 15.4.9) indicates that the target resource has permanently moved to a different URI referenced by the Location response field ([HTTP], Section 10.2.2). Likewise, a response with either 302 (Found, [HTTP], Section 15.4.3 or 307 (Temporary Redirect, [HTTP], Section 15.4.8) indicates that the target resource has temporarily moved. In all four cases, the server is suggesting that the user agent can accomplish its original QUERY request by sending a similar QUERY request to the new target URI referenced by Location.¶
Note that the exceptions for redirecting a POST as a GET request after a 301 or 302 response do not apply to QUERY requests.¶
A response to QUERY with the status code 303 (See Other, Section 15.4.4 of [HTTP]) indicates that the original query can be accomplished via a normal retrieval request on the URI referenced by the Location response field ([HTTP], Section 10.2.2). For HTTP, this means sending a GET request to the new target URI, as illustrated by the example in Appendix A.4.3.¶
A conditional QUERY requests that the selected representation (i.e., the query results, after any content negotiation) be returned in the response only under the circumstances described by the conditional header field(s), as defined in Section 13 of [HTTP].¶
The response to a QUERY method is cacheable; a cache MAY use it to satisfy subsequent QUERY requests as per Section 4 of [HTTP-CACHING]).¶
The cache key for a QUERY request (see Section 2 of [HTTP-CACHING]) MUST incorporate the request content.¶
Caches MAY remove semantically insignificant differences first, thereby improving cache efficiency.¶
For instance, by¶
Note that any such transformation is performed solely for the purpose of generating a cache key; it does not change the request itself.¶
Clients can indicate, using the "no-transform" cache directive (Section 5.2.1.6 of [HTTP-CACHING]), that they wish that no such transformation happens (but note that this directive is just advisory).¶
The semantics of Range Requests for QUERY are identical to those for GET, as defined in Section 14 of [HTTP].¶
The "Accept-Query" response header field can be used by a resource to directly signal support for the QUERY method while identifying the specific query format media type(s) that may be used.¶
Accept-Query contains a list of media ranges (Section 12.5.1 of [HTTP]) using "Structured Fields" syntax ([STRUCTURED-FIELDS]). Media ranges are represented by a List Structured Header Field of either Tokens or Strings, containing the media range value without parameters.¶
Media type parameters, if any, are mapped to Structured Field Parameters of type String or Token. The choice of Token vs. String is semantically insignificant. That is, recipients MAY convert Tokens to Strings, but MUST NOT process them differently based on the received type.¶
Media types do not exactly map to Tokens, for instance they allow a leading digit. In cases like these, the String format needs to be used.¶
The only supported uses of wildcards are "*/*", which matches any type, or "xxxx/*", which matches any subtype of the indicated type.¶
The order of types listed in the field value is not significant.¶
The value of the Accept-Query field applies to every URI on the server that shares the same path; in other words, the query component is ignored. If requests to the same resource return different Accept-Query values, the most recently received fresh value (per Section 4.2 of [HTTP-CACHING]) is used.¶
Example:¶
Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"
Although the syntax for this field appears to be similar to other fields, such as "Accept" (Section 12.5.1 of [HTTP]), it is a Structured Field and thus MUST be processed as specified in Section 4 of [STRUCTURED-FIELDS].¶
The QUERY method is subject to the same general security considerations as all HTTP methods as described in [HTTP].¶
It can be used as an alternative to passing request information in the URI (e.g., in the query component). This is preferred in some cases, as the URI is more likely to be logged or otherwise processed by intermediaries than the request content. In other cases, where the query contains sensitive information, the potential for logging of the URI might motivate the use of QUERY over GET.¶
If a server creates a temporary resource to represent the results of a QUERY request (e.g., for use in the Location or Content-Location field) and the request contains sensitive information that cannot be logged, then the URI of this resource SHOULD be chosen such that it does not include any sensitive portions of the original request content.¶
Caches that normalize QUERY content incorrectly or in ways that are significantly different from how the resource processes the content can return an incorrect response if normalization results in a false positive.¶
IANA is requested to add the QUERY method to the HTTP Method Registry at <http://www.iana.org/assignments/http-methods> (see Section 16.3.1 of [HTTP]).¶
| Method Name | Safe | Idempotent | Specification |
|---|---|---|---|
| QUERY | Yes | Yes | Section 2 |
IANA is requested to add the Accept-Query field to the HTTP Field Name Registry at <https://www.iana.org/assignments/http-fields> (see Section 16.1.1 of [HTTP]).¶
| Field Name | Status | Structured Type | Reference | Comments |
|---|---|---|---|---|
| Accept-Query | permanent | List | Section 3 of this document. |
The examples below are for illustrative purposes only; if one needs to send queries that are actually this short, it is likely better to use GET.¶
The media type used in most examples is "application/x-www-form-urlencoded" (as used in POST requests from browser user clients, defined in "application/x-www-form-urlencoded" in [URL]). The Content-Length fields have been omitted for brevity.¶
A simple query with a direct response:¶
QUERY /contacts HTTP/1.1 Host: example.org Content-Type: application/x-www-form-urlencoded Accept: application/json select=surname,givenname,email&limit=10&match=%22email=*@example.*%22
Response:¶
HTTP/1.1 200 OK
Content-Type: application/json
[
{ "surname": "Smith",
"givenname": "John",
"email": "smith@example.org" },
{ "surname": "Jones",
"givenname": "Sally",
"email": "sally.jones@example.com" },
{ "surname": "Dubois",
"givenname": "Camille",
"email": "camille.dubois@example.net" }
]
A simple way to discover support for QUERY is provided by the OPTIONS (Section 9.3.7 of [HTTP]) method:¶
OPTIONS /contacts HTTP/1.1 Host: example.org
Response:¶
HTTP/1.1 200 OK Allow: GET, QUERY, OPTIONS, HEAD
The Allow response field (Section 10.2.1 of [HTTP]) denotes the set of supported methods on the specified resource.¶
There are alternatives to the use of OPTIONS. For instance, a QUERY request can be tried without prior knowledge of server support. The server would then either process the request, or could respond with a 4xx status such as 405 (Method Not Allowed, Section 15.5.6 of [HTTP]), including the Allow response field.¶
Discovery of supported media types for QUERY is possible via the Accept-Query (Section 3) response field:¶
HEAD /contacts HTTP/1.1 Host: example.org
Response:¶
HTTP/1.1 200 OK Content-Type: application/xhtml Accept-Query: application/x-www-form-urlencoded, application/sql
Responses to which request methods will contain Accept-Query will depend on the resource being accessed.¶
An alternative to checking Accept-Query would be to make a QUERY request, and then -- in case of a 4xx status such as 415 (Unsupported Media Type, Section 15.5.16 of [HTTP]) response -- to inspect the Accept (Section 12.5.1 of [HTTP]) response field:¶
HTTP/1.1 415 Unsupported Media Type Content-Type: application/xhtml Accept: application/x-www-form-urlencoded, application/sql
As described in Sections 2.2 and 2.3, the Content-Location and Location response fields in success responses (2xx, Section 15.3 of [HTTP]) provide a way to identify alternate resources that will respond to GET requests, either for the received result of the request, or for future requests to perform the same operation. Going back to the example from Appendix A.1:¶
QUERY /contacts HTTP/1.1 Host: example.org Content-Type: application/x-www-form-urlencoded Accept: application/json select=surname,givenname,email&limit=10&match=%22email=*@example.*%22
Response:¶
HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/stored-results/17
Location: /contacts/stored-queries/42
Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
Date: Sun, 17 Nov 2024, 16:10:24 GMT
[
{ "surname": "Smith",
"givenname": "John",
"email": "smith@example.org" },
{ "surname": "Jones",
"givenname": "Sally",
"email": "sally.jones@example.com" },
{ "surname": "Dubois",
"givenname": "Camille",
"email": "camille.dubois@example.net" }
]
The Content-Location response field received above identifies a resource holding the result for the QUERY response it appeared on:¶
GET /contacts/stored-results/17 HTTP/1.1 Host: example.org Accept: application/json
Response:¶
HTTP/1.1 200 OK
Last-Modified: Sat, 25 Aug 2012 23:34:45 GMT
Date: Sun, 17 Nov 2024, 16:10:25 GMT
[
{ "surname": "Smith",
"givenname": "John",
"email": "smith@example.org" },
{ "surname": "Jones",
"givenname": "Sally",
"email": "sally.jones@example.com" },
{ "surname": "Dubois",
"givenname": "Camille",
"email": "camille.dubois@example.net" }
]
Note that there's no guarantee that the server will implement this resource indefinitely, so, after an error response, the client would need to redo the original QUERY request in order to obtain a new alternative location.¶
The Location response field identifies a resource that will respond to GET with a current result for the same process and parameters as the original QUERY request.¶
GET /contacts/stored-queries/42 HTTP/1.1 Host: example.org Accept: application/json
In this example, one entry was removed at 2024-11-17T16:12:01Z (as indicated in the Last-Modified field), so the response only contains two entries:¶
HTTP/1.1 200 OK
Content-Type: application/json
Last-Modified: Sun, 17 November 2024, 16:12:01 GMT
ETag: "42-1"
Date: Sun, 17 Nov 2024, 16:13:17 GMT
[
{ "surname": "Smith",
"givenname": "John",
"email": "smith@example.org" },
{ "surname": "Dubois",
"givenname": "Camille",
"email": "camille.dubois@example.net" }
]
Assuming that the server still exposes the resource and that there was no change in the query result, a subsequent conditional GET request with¶
If-None-Match: "42-1"
would result in a 304 response (Not Modified, Section 15.4.5 of [HTTP]).¶
Servers can send "indirect" responses (Section 2.4) using the status code 303 (See Other, Section 15.4.4 of [HTTP]).¶
Given the request at the beginning of Appendix A.4, a server might respond with:¶
HTTP/1.1 303 See Other Content-Type: text/plain Date: Sun, 17 Nov 2024, 16:13:17 GMT Location: /contacts/stored-queries/42 See stored query at "/contacts/stored-queries/42".
This is similar to including Location on a direct response, except that no result for the query is returned. This allows the server to only generate or reuse an alternative resource. This resource could then be used as shown in Appendix A.4.2.¶
The request below uses XSLT ([XSLT]) to extract errata information summarized per year and the defined errata types.¶
QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/xslt+xml
Accept: application/xml, text/csv
<transform xmlns="http://www.w3.org/1999/XSL/Transform"
xmlns:j="http://www.w3.org/2005/xpath-functions"
version="3.0">
<output method="text"/>
<param name="input"/>
<variable name="json"
select="json-to-xml(unparsed-text($input))"/>
<variable name="sc">errata_status_code</variable>
<variable name="sd">submit_date</variable>
<template match="/">
<text>year, total, rejected, verified, hdu, reported</text>
<text> </text>
<variable name="en" select="$json//j:map"/>
<for-each-group select="$en"
group-by="substring-before(j:string[@key=$sd],'-')">
<sort select="current-grouping-key()"/>
<variable name="year" select="current-grouping-key()"/>
<variable name="errata" select=
"$en[$year=substring-before(j:string[@key=$sd],'-')]"/>
<value-of select="concat(
$year,
', ',
count($errata),
', ',
count($errata['Rejected'=j:string[@key=$sc]]),
', ',
count($errata['Verified'=j:string[@key=$sc]]),
', ',
count(
$errata['Held for Document Update'=j:string[@key=$sc]]),
', ',
count($errata['Reported'=j:string[@key=$sc]]),
' ')"/>
</for-each-group>
</template>
</transform>
Response:¶
HTTP/1.1 200 OK Content-Type: text/csv Accept-Query: "application/jsonpath", "application/xslt+xml" Date: Wed, 19 Feb 2025, 17:10:01 GMT year, total, rejected, verified, hdu, reported 2000, 14, 0, 14, 0, 0 2001, 72, 1, 70, 1, 0 2002, 124, 8, 104, 12, 0 2003, 63, 0, 61, 2, 0 2004, 89, 1, 83, 5, 0 2005, 156, 10, 96, 50, 0 2006, 444, 54, 176, 214, 0 2007, 429, 48, 188, 193, 0 2008, 423, 52, 165, 206, 0 2009, 331, 39, 148, 144, 0 2010, 538, 80, 232, 222, 4 2011, 367, 47, 170, 150, 0 2012, 348, 54, 149, 145, 0 2013, 341, 61, 169, 106, 5 2014, 342, 73, 180, 72, 17 2015, 343, 79, 145, 89, 30 2016, 295, 46, 122, 82, 45 2017, 303, 46, 120, 84, 53 2018, 350, 61, 118, 98, 73 2019, 335, 47, 131, 94, 63 2020, 387, 68, 117, 123, 79 2021, 321, 44, 148, 63, 66 2022, 358, 37, 198, 40, 83 2023, 262, 38, 121, 33, 70 2024, 322, 33, 125, 23, 141 9999, 1, 0, 0, 1, 0
Note the Accept-Query response field indicating that another query format -- JSONPath ([RFC9535]) -- is supported as well. The request below would report the identifiers of all rejected errata submitted since 2024:¶
QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/jsonpath
Accept: application/json
$..[
?@.errata_status_code=="Rejected"
&& @.submit_date>"2024"
]
["doc-id"]
Response:¶
HTTP/1.1 200 OK Content-Type: application/json Accept-Query: "application/jsonpath", "application/xslt+xml" Date: Thu, 20 Feb 2025, 09:55:42 GMT Last-Modified: Thu, 20 Feb 2025 06:10:01 GMT [ "RFC1185","RFC8407","RFC6350","RFC8467","RFC1157","RFC9543", "RFC9076","RFC7656","RFC2822","RFC9460","RFC2104","RFC6797", "RFC9499","RFC9557","RFC2131","RFC2328","RFC9001","RFC3325", "RFC9438","RFC2526","RFC2985","RFC7643","RFC9132","RFC6376", "RFC9110","RFC9460","RFC7748","RFC9497","RFC8463","RFC4035", "RFC7239","RFC9083","RFC9537","RFC9537","RFC9420","RFC9000", "RFC9656","RFC9110","RFC2324","RFC2549","RFC6797","RFC2549", "RFC8894" ]
This section is to be removed before publishing as an RFC.¶
We thank all members of the HTTP Working Group for ideas, reviews, and feedback.¶
The following individuals deserve special recognition: Carsten Bormann, Mark Nottingham, Martin Thomson, Michael Thornburgh, Roberto Polli, Roy Fielding, and Will Hawkins.¶
Ashok Malhotra participated in early discussions leading to this specification:¶