This specification defines the QUERY method for HTTP. A QUERY requests that the request target process the enclosed content in a safe and idempotent manner and then respond with the result of that processing. This is similar to POST requests, but QUERY requests can be automatically repeated or restarted without concern for partial state changes.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any
errata, and how to provide feedback on it may be obtained at
https://
Copyright (c) 2026 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://
This specification defines the HTTP QUERY request method as a means of making a safe, idempotent request (Section 9.2 of [HTTP]) that encloses a representation describing how the request is to be processed by the target resource.¶
A common query pattern is:¶
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:¶
In this variation, however, it is not readily apparent -- without 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:¶
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 to a specific query result, for later use in a GET request.¶
Summarizing:¶
This document uses terminology defined in Section 3 of [HTTP].¶
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 key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
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 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.¶
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 is 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.3 and 2.4).¶
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 equivalent resource for any given QUERY request is a resource that responds to GET requests, represents that QUERY request and its target, and takes both message content and metadata into account (Section 6 of [HTTP]). In particular, this includes representation metadata (Section 8 of [HTTP]) such as the content's media type.¶
In other words, the equivalent resource is derived from the resource implementing QUERY by incorporating the request content.¶
The term equivalent resource is used as a means to define
behavior for other HTTP aspects, such as selected representations
A successful response (2xx, Section 15.3 of [HTTP])
can include a Content
See Appendix A.4.1 for an example.¶
A server can assign a URI to the equivalent resource (Section 2.2) of a QUERY request. If the server does so, the URI of that 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's URI might be temporary; if a future request fails, the client can retry using the original QUERY request target 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 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 status codes 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 the 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.¶
The selected representation (Section 3.2 of [HTTP]) of a QUERY request is the same as for a GET request to the equivalent resource (Section 2.2) of that QUERY request.¶
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].¶
See Appendix A.5 for examples.¶
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 (Section 2 of [HTTP-CACHING]) MUST incorporate the request content (Section 6 of [HTTP-CACHING]) and related metadata (Section 8 of [HTTP]).¶
To improve cache efficiency, caches MAY remove semantically insignificant differences from request content and related metadata first. 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).¶
Note that caching QUERY method responses is inherently more complex than caching responses to GET, as complete reading of the request's content is needed in order to determine the cache key. If a QUERY response supplies a Location response field (Section 2.4) to indicate a URI for an equivalent resource (Section 2.2), clients can switch to GET for subsequent requests, thereby simplifying processing.¶
The semantics of Range Requests for QUERY are identical to those for GET, as defined in Section 14 of [HTTP]. Byte Range Requests (the only range unit defined at the time of writing), however, offer little value for the results of a QUERY request.¶
Query formats often define their own way of limiting or paging through result sets, such as with "FETCH FIRST ... ROWS ONLY" in SQL. It is expected that these built-in features will be used instead of HTTP Range Requests.¶
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
Media type parameters, if any, are mapped to Structured Field Parameters with the String or Token type. The choice of Token versus 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.¶
For example:¶
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
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
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.¶
A QUERY request from user agents implementing Cross-Origin Resource Sharing (CORS) will require a "preflight" request, as QUERY does not belong to the set of CORS-safelisted methods (see [FETCH]).¶
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
Below is a simple query with a direct response:¶
Response:¶
A simple way to discover support for QUERY is provided by the OPTIONS (Section 9.3.7 of [HTTP]) method:¶
Response:¶
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 it could respond with a 4xx status such as 405 (Method Not Allowed, Section 15.5.6 of [HTTP]), including the Allow response field.¶
The discovery of supported media types for QUERY is possible via the Accept-Query response field (Section 3):¶
Response:¶
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 a 415 response (Unsupported Media Type, Section 15.5.16 of [HTTP]) -- to inspect the Accept response field (Section 12.5.1 of [HTTP]):¶
As described in Sections 2.3 and
2.4, the Content
Response:¶
The Content
Response:¶
Note that there is 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.¶
In this example, one entry was removed at 2024
Assuming that the server still exposes the resource and that there was no change in the query result, a subsequent conditional GET request with the following:¶
would result in a 304 (Not Modified) response (Section 15.4.5 of [HTTP]).¶
Servers can send "indirect" responses (Section 2.5) 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:¶
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.¶
Consider a resource implementing QUERY that supports "application
Response:¶
Here, the server has assigned the path "
Later on, the client repeats the query, but specifies that results should only be returned when changed:¶
The data being queried did not change, therefore the server responds with:¶
As the server identified a URI for the equivalent resource, that resource can be accessed with GET. In particular, this avoids resending the query request's content:¶
Here, the state of the data set indeed changed, so new content is returned:¶
(Note the change in the row for this decade.)¶
The diagrams below illustrate the use of conditional requests and how they can differ when a URI is assigned to the equivalent resource (and when the client is taking advantage of it). The fictitious field name "Validator" is used for demonstration purposes.¶
Client Resource QUERY with content 200 OK Validator: foo QUERY with content (conditional on 'foo') 304 Not Modified Validator: foo State Change QUERY with content (conditional on 'foo') 200 OK Validator: bar
¶
Client Resource QUERY with content Equivalent Resource (generates /xyz) 200 OK Validator: foo Location: /xyz GET (conditional on 'foo') 304 Not Modified Validator: foo State Change GET (conditional on 'foo') 200 OK Validator: bar
¶
The following examples show requests on a JSON-shaped [RFC8259] database of RFC errata.¶
The request below uses eXtensible Stylesheet Language Transformations (XSLT) to extract errata information summarized per year and the defined errata types.¶
Response:¶
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:¶
Response:¶
The "Hypertext Transfer Protocol (HTTP) Method Registry" (<http://
It would have been possible to reuse any of these, updating it in a way that it matches what this specification defines as the new method "QUERY". Indeed, the early stages of this specification used "SEARCH".¶
The method name "QUERY" ultimately was chosen because:¶
We thank all members of the HTTP Working Group for their 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:¶
Ashok Malhotra
Discussion on this HTTP method was reopened by Asbjørn Ulsberg during the HTTP Workshop in 2019:¶
Asbjørn Ulsberg
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。