Since the HTTP QUERY method has been added, I read RFC 10008.

A method called QUERY was added to HTTP.

It is the RFC 10008 “The HTTP QUERY Method” published in June 2026 (source). This is not RFC 1008, but the five‑digit RFC 10008.

As its name suggests, it is a method for querying a server, allowing search criteria to be placed in the request body.

If that were all, POST would seem to be sufficient. In fact, it is not uncommon to implement complex search APIs using POST.

The reason QUERY was added is not only that it can carry a request body, but also that the request can be explicitly marked as read‑only in HTTP, indicating that the same request may be resent without side effects.

When searching with GET, criteria end up in the URI

For simple searches, using GET’s query parameters is fine.

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

However, as search criteria become more numerous, become nested, or you want to pass a fairly complex expression, cramming everything into the URI becomes unwieldy.

There is no simple, universal limit on URI length that all clients, proxies, CDNs, and servers along the path share. How far a long URI can be transmitted depends on the actual deployment.

There is also the overhead of encoding structures such as JSON into a form that can be represented in a URI. Moreover, because URIs are readily retained in access logs, histories, and similar records, they may contain search criteria that are difficult to handle.

So, does that mean we should simply attach a body to GET? That, too, is not a standard solution.

According to the definition of GET in RFC 9110 (source), a body received with a GET request has no generally defined meaning. Some implementations may reject such requests due to the risk of request smuggling, and unless you are sending them directly to an origin server that is known to handle them, clients should not attach a body to a GET request.

Even if the sender and the application support it, intermediate implementations may not interpret it the same way.

POST can carry a body

Using POST for searches that are awkward with GET is already widely adopted.

POST /feed/search HTTP/1.1
Host: example.org
Content-Type: application/json

{
  "query": "foo",
  "limit": 10,
  "sort": "-published"
}

With this, you can place complex criteria in the request body.

On the other hand, POST is also a method used for creating resources or changing state. Even if a particular POST request is actually read‑only, the general HTTP mechanisms cannot determine whether it is a safe, idempotent query that can be safely resent.

Deciding whether to automatically retry when the connection drops, or whether to reuse a response for the same request, requires knowledge specific to that API.

QUERY defines this meaning within the HTTP method itself.

QUERY is a safe, idempotent method that carries a body

When the same search is expressed with QUERY, it looks like this:

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/json
Accept: application/json

{
  "query": "foo",
  "limit": 10,
  "sort": "-published"
}

The content of the query is determined by the request body and Content-Type, while the scope is determined by the target resource.

A rough comparison of GET, QUERY, and POST is shown below.

Here, “safe” means that the client does not request any change to the state of the target resource. It does not prohibit side effects such as increasing access logs, consuming computational resources, or the server creating a temporary resource that represents the query result.

Because it is idempotent, if the connection drops before a response is received, the client or intermediate systems may resend the same QUERY.

Even a search API built with POST can achieve the same behavior through application design. However, with QUERY, this property can be inferred directly from the HTTP method itself rather than relying on API‑specific conventions.

The QUERY proposal did not appear out of nowhere

The discussion of an HTTP method for searching is not new.

WebDAV defined the SEARCH method in RFC 5323 from 2008 (source). Furthermore, in 2015 a draft titled draft-snell-search-method-00 (source) was published, aiming to extend this SEARCH method to general HTTP searches.

After several revisions, that draft was taken over by the HTTP Working Group’s draft-ietf-httpbis-safe-method-w-body (source) in 2021.

Initially the plan was to use the existing SEARCH method, but ultimately it was given a new name, QUERY.

RFC 10008’s Appendix B explains that the existing SEARCH, PROPFIND, and REPORT methods originate from WebDAV and are tied to designs that embed the request’s meaning in XML content. Rather than extending the meaning of existing methods, QUERY was chosen because its relationship with a URI’s query component is easier to understand.

Counting from the 2015 individual draft, it took roughly eleven years to become an RFC. It was not a case of a method being arbitrarily added to HTTP on a whim.

Content‑Type is required

In QUERY, the request body itself is the query, so specifying the Content‑Type becomes important.

The server must reject the request if the Content‑Type is missing or does not match the content. The RFC lists the following status codes as appropriate in various situations.

The server can use the new Accept-Query response header to indicate which query formats it accepts.

Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

Allow: GET, QUERY, OPTIONS, HEAD indicates support for the QUERY method itself, while Accept-Query specifies the media types that can be used in the request body.

The cache key must also include the body

Responses to QUERY can be cached.

However, even if the URI is the same, a request with a different body constitutes a different query.

QUERY /users

{"country":"JP"}

QUERY /users

{"country":"US"}

Therefore, a cache that handles QUERY must include the request body and its associated metadata in the cache key, not just the URI.

Normalization of cases where the byte representation differs—such as whitespace in JSON or the order of properties—while the logical query is the same, is permitted. However, normalizing incorrectly can cause different queries to be treated as identical and receive the same result.

It is clear that caching is more involved than with GET.

URIs can be attached to the query and its result

RFC 10008 also includes a mechanism for moving from a QUERY to a GET after the query has been executed.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/stored-results/17
Location: /contacts/stored-queries/42

Content-Location is the URI that can be used later to retrieve the result obtained in this request.

Location is the URI for re‑executing the same query with a GET that has no body. If the underlying data changes, the result obtained from this URI may also change.

Content-Location
  -> Retrieve the result of this run

Location
  -> Retrieve the current result under the same conditions

Even clients or intermediary systems that do not support caching for QUERY will, after executing a QUERY once, fall back to ordinary GET requests and standard URIs.

Can it be used immediately with regular APIs?

The specification has been published as an IETF Standards Track document, and both QUERY and Accept-Query have been registered with IANA.

However, the fact that it has become an RFC is separate from whether the web servers, frameworks, CDNs, or WAFs you are currently using can handle it without modification. There is a possibility that it will be rejected as an unknown HTTP method, or that the cache will be unable to generate a key that includes the request body.

When a request is sent cross‑origin from a browser, QUERY is not a CORS‑safelisted method, so a preflight request will also be triggered.

The RFC itself notes that for short, example‑type queries, using GET is preferable. It is not intended to replace everything—even simple list retrievals—with QUERY.

At this point, it can be viewed simply as a standardized option for designing new APIs that involve complex search criteria. If you actually adopt it, you need to verify that the entire path from the client to the origin can handle QUERY.

From a single GET to this point

Reading the “History of HTTP” section in RFC 9110 explains that the original HTTP was a simple mechanism that merely retrieved hypertext documents specified by a path using GET. (source)

HTTP remains stateless today. This does not mean that servers must not store data; rather, each request can be understood on its own without relying on previous requests on the same connection.

QUERY does not change this principle either. The conditions required for a query are placed in the request body and metadata, so the meaning of the request is determined solely by that request. For queries or results that need to be reused, the server assigns a URI, representing them as a resource that can be fetched with GET thereafter.

HTTP, which began with retrieving a document via a single GET, has added methods that allow you to send complex queries in the request body and to cache the results or reuse them from another URI. Yet the fundamental statelessness remains.

This specification conveys the evolution over time of HTTP’s scope, expanding from document retrieval to general‑purpose APIs.

Summary

QUERY, as defined in RFC 10008, is an HTTP method that fills the gap in the handling of search APIs that lies between GET and POST.

It is as safe and idempotent as GET, while allowing the query to be placed in the request body like POST. It also supports response caching and conditional requests, and it defines how to assign URIs to the query itself and its results.

On the other hand, because the cache key must include the request body, existing middleware may not be able to support it out of the box.

Since a search API can be built with POST and will work, the issue is not immediately obvious as one that would cause trouble without QUERY. However, being able to express that a query is read‑only as part of the method’s semantics—rather than relying on an external HTTP convention—represents a fairly significant difference.