What Is the HTTP QUERY Method and How Does It Differ from GET/POST?

1. Introduction

The HTTP QUERY request method is a safe and idempotent way to send a request that can include a request body. It is useful when a GET request would exceed URI length limits, allowing large query parameters to be sent in the payload.

<code>GET /feed?q=foo&limit=10&sort=-published HTTP/1.1
Host: example.org</code>

When query parameters grow to several kilobytes, many implementations cannot handle them via GET, so POST is often used as a workaround, placing the parameters in the request body instead of the URI.

Typical POST request example

<code>POST /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published</code>

However, POST shares the same basic limitation as GET: it is not explicitly marked as safe or idempotent, making caching and automatic retries less straightforward.

The QUERY method offers a middle ground between GET and POST. Like POST, the query input is transmitted in the request payload, but unlike POST, QUERY is explicitly defined as safe and idempotent, allowing caches and automatic retries to work correctly.

2. QUERY method

QUERY is used to initiate a server‑side query. Unlike GET, which returns a representation of the resource identified by the URI, QUERY requests the server to execute a query operation over a dataset described by the request payload. The response payload is not assumed to be a representation of the resource identified by the request URI.

The request payload defines the query. Implementations may use any content type that conveys appropriate query semantics.

QUERY requests are safe and idempotent for the resource identified by the request URI, meaning they do not change the target resource's state, though the server may allocate compute and memory resources to process the query.

A successful QUERY response may indicate the result in various ways, such as a 204 No Content when there are no results, or a 200 with a payload describing the outcome. Servers may also respond with a 3xx redirect containing a Location header to an alternative URI that can be fetched with GET.

2.1 Caching

The response to a QUERY request can be cached; caches may use HTTP caching mechanisms to satisfy subsequent QUERY requests.

The cache key must include the request content, and caches should normalize the request content to remove semantically irrelevant differences, improving cache efficiency.

Remove content encoding

Normalize based on any media type suffix in the Content‑Type header (e.g., "+json")

Normalize based on the semantic meaning of the content itself

Note that such normalization is only for generating the cache key and does not alter the request itself.

2.2 “Accept-Query” header

Servers can use the “Accept-Query” response header to signal support for the QUERY method and to indicate which query format media types are acceptable.

<code>Accept-Query = 1#media-type</code>

The Accept-Query header lists media types (and optional parameters) defined in RFC 7231 §8.3.1, in a comma‑separated list where order is insignificant.

3. Examples

The following non‑normative examples use a simple, hypothetical plain‑text query syntax based on SQL and return results as comma‑separated values. Implementations may use any format for request and response.

3.1 Direct response simple QUERY

<code>QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 10</code>

Response:

<code>HTTP/1.1 200 OK
Content-Type: text/csv

surname, givenname, email
Smith, John, [email protected]
Jones, Sally, [email protected]
Dubois, Camille, [email protected]</code>

3.2 Indirect response simple QUERY (303 See Other)

<code>QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 10</code>

Response:

<code>HTTP/1.1 303 See Other
Location: http://example.org/contacts/query123</code>

Retrieve the query result:

<code>GET /contacts/query123 HTTP/1.1
Host: example.org</code>

Response:

<code>HTTP/1.1 200 OK
Content-Type: text/csv

surname, givenname, email
Smith, John, [email protected]
Jones, Sally, [email protected]
Dubois, Camille, [email protected]</code>

5. Conclusion

The HTTP QUERY method is a promising proposal that could simplify server‑side data request interfaces by providing a safe, idempotent alternative to choosing between GET and POST.