HTTP QUERY Method: The Safe GET With a Body (RFC 10008)

Every backend engineer eventually hits the same wall: a search endpoint whose parameters no longer fit in a URL. A faceted product filter, a GraphQL-style field selection, a geospatial polygon — the query is structured data, not a handful of string parameters. HTTP has historically given you two poor options for that, and in June 2026 the IETF finally shipped a third.

That third option is QUERY, published as RFC 10008, The HTTP QUERY Method. It grew out of the working-group draft named draft-ietf-httpbis-safe-method-w-body, and that draft name is the whole idea in one phrase: a safe method that is allowed to carry a body. Before we get to QUERY, it is worth being precise about why the two existing options hurt.

GET with a body was never safe

The instinct is to put the body on a GET, since a search reads data and GET is the read method. The specification disagrees. RFC 9110, the core HTTP semantics document, states plainly that content received in a GET request has no generally defined semantics, cannot alter the meaning or target of the request, and might lead some implementations to reject the request and close the connection because of its potential as a request smuggling attack. In practice: some proxies silently drop the body, and some treat it as an attack. A request that behaves differently depending on which intermediary it passes through is not something you can ship.

GET /contacts?select=surname,givenname,email&limit=10&match=%22email%3D*%40example.*%22 HTTP/1.1
Host: example.org

# RFC 9110 §9.3.1: content in a GET request "has no generally
# defined semantics" and may be rejected as request smuggling.

POST for search: it works, but gives up too much

So most of us reach for POST. It carries any body you like and every client and proxy understands it. The problem is what POST means. POST is neither safe, idempotent, nor cacheable — it is defined as a method that may change server state. That single definition costs you three concrete things. A dropped connection cannot be retried automatically, because nothing guarantees the first attempt did not already mutate something. A CDN or shared cache cannot reuse the response. And a reader of your logs cannot tell a state-changing write apart from a read that merely happens to carry a big body. You end up documenting this POST is really a read in prose that no cache or proxy will ever read.

QUERY: a body like POST, guarantees like GET

QUERY resolves the tension. RFC 10008 defines it as a method that asks the target resource to process the enclosed request content in a safe and idempotent manner and return the result. The content — JSON, form-encoded, whatever media type you declare — is the query. Because the method is defined as safe, the server promises the request changes no state; because it is idempotent, a client or proxy may retry it after a network blip without fear; and because the response is cacheable, a shared cache may reuse it for later identical QUERY requests. It is, quite literally, the read semantics of GET with the request body of POST.

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

{ "select": ["surname","givenname","email"], "limit": 10, "match": "email=*@example.*" }

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/responses/42

[ { "surname": "Smith", "givenname": "John", "email": "[email protected]" } ]

Safe, idempotent, cacheable — what each guarantee buys you

These three words are not decoration; each one unlocks a specific behavior in the machinery between your client and your server.

• Safe means intermediaries and the client know the request is read-only, so prefetching, link-following, and automated retries are all legitimate — the same freedom they already grant GET.
• Idempotent means a request that fails mid-flight can be retried automatically, because repeating it has the same effect as sending it once. This is the guarantee POST can never give a search.
• Cacheable means a shared cache may store the response and serve it to the next identical query, cutting origin load on hot searches without you building a bespoke cache layer.

The cache key lives in the body

There is one genuinely new thing to get right. For GET, the cache key is the URI. For QUERY, the query is in the body, so the URI alone is not enough. RFC 10008 requires that the cache key for a QUERY request incorporate the request content and related metadata, not just the target URI. In practice a cache must hash the body — respecting content type and relevant headers — to distinguish two different searches sent to the same path. Caches that support QUERY do this for you; the point is that a naive URI-only cache will happily return the wrong results if you bolt QUERY onto it without support.

Three ways to run the same search

Can you use it today?

QUERY is a Proposed Standard, not a future promise, but tooling is still catching up — so the honest answer is on the server, increasingly yes; in the browser, not yet.

• The .NET 10 and ASP.NET Core 10 stack ships first-class support: HttpMethod.Query on the client and HttpMethods.Query with an IsQuery helper on the server, so you can route QUERY requests today.
• Browsers cannot send QUERY from fetch or XMLHttpRequest yet, and MDN has no dedicated QUERY page — only a tracking issue — so public web clients still need a fallback.
• The pragmatic pattern for now is service-to-service QUERY with a parallel POST search endpoint for browsers, sharing the same handler, until client support lands.

I would not rip out a working POST /search tomorrow. But if you are designing a new internal search or filter API between services you control, QUERY is the correct method — it finally lets a read that needs a body stay a read, all the way down through every cache and proxy on the path. Reach for it there first, keep POST as the browser-facing fallback, and let the ecosystem catch up around you.