The HTTP QUERY method RFC 10008 ends the GET or POST bind

The IETF published RFC 10008 in June 2026, defining QUERY. It is the first new standard HTTP method since PATCH in 2010.

The HTTP QUERY method RFC 10008 describes does one thing, and it is the thing every complex search endpoint has been unable to have: a request body that remains safe, idempotent and cacheable.

The trade-off it removes

Anyone who has built a search or reporting API has had this argument.

Use GET and the filters go in the URL. GET is safe and idempotent, so intermediaries can cache it, clients can retry it, and a crawler cannot break anything by following it. But URLs have practical length limits that a nested filter object exceeds quickly, and every parameter lands in access logs, browser history and referrer headers — which is a real problem when the filter contains a customer identifier or a date of birth.

Use POST and the body problem disappears. But POST is neither safe nor idempotent, so caches must not store the response, clients cannot retry safely, and you have told every intermediary that this request might have changed something. It has not. You are lying to the network for the sake of a body.

Teams have papered over this for fifteen years — POST endpoints named /search that everyone knows are reads, GET endpoints with base64-encoded filter blobs, custom headers, X-HTTP-Method-Override. All of it works. None of it lets a cache do its job.

What the specification actually says

The RFC defines QUERY as a request that the target resource process the enclosed content in a safe and idempotent manner and respond with the result of that processing.

Three properties follow, and each is stated explicitly:

• Safe. QUERY requests are safe with regard to the target resource — they do not change it.
• Idempotent. They can be retried or repeated when needed, which means a client library can retry a timeout without asking whether that is dangerous.
• Cacheable. The response is cacheable and a cache may use it to satisfy subsequent QUERY requests. Critically, the cache key must incorporate the request content and related metadata.

That last clause is the whole design. A cache keyed only on the URL would collide every distinct search against one entry; requiring the body in the key is what makes body-carrying caching coherent at all.

Accept-Query

The RFC also defines an Accept-Query response header. A resource uses it to signal that it supports QUERY and to name the query format media types it accepts.

This is more useful than it first appears. It gives clients a discovery mechanism rather than a guess-and-handle-405 dance, and it lets a service expose several query grammars — a simple filter document and a richer one — from the same endpoint, declared rather than documented.

The two traps the RFC calls out

Both are worth reading before anyone gets enthusiastic.

Temporary resources can leak the query. If a server creates a temporary resource in response to a QUERY, the specification says the URI should be chosen so that it does not include any sensitive portion of the original request content. Since avoiding sensitive data in URLs is a large part of why you reached for QUERY, undoing it in the response location would be an unusually complete own goal.

Cache normalisation can return the wrong answer. Caches that normalise QUERY content incorrectly can produce a false positive and serve a response belonging to a different query. Two filter documents that differ only in key order or whitespace are semantically identical; whether your cache treats them as the same entry is now a correctness question, not a hit-rate question.

The practical implication is that if you put a CDN or reverse proxy in front of a QUERY endpoint, you need to know exactly how it derives the cache key before you trust it.

What it looks like in practice

A report endpoint today usually looks like one of two things. Either a GET with a filter serialised into the query string, which works until somebody selects forty product categories and the request is rejected by a proxy nobody controls. Or a POST to /reports/search with a JSON body, which always works and is never cached, so an identical dashboard refresh by ten people costs ten full executions.

With QUERY the same request carries its JSON body and the response can be stored. Ten identical dashboard loads become one execution and nine cache hits, without an application-level cache, without a hashing scheme invented in-house, and without anybody having to remember to invalidate it.

That is the whole benefit, and whether it is worth anything depends entirely on how repetitive your read traffic is. For a reporting surface refreshed by many people looking at the same figures, it is significant. For a search where every query is unique, the cache never hits and QUERY buys you only honesty about the method.

Should you use it yet

Adoption is early and honest about it. Support has been merged into Rust's http crate, and it is being tracked across .NET, Axum, Quarkus and Bruno. Real-world adoption will take years, and the RFC positions QUERY as additive rather than a replacement for anything.

So the answer for most teams today is no, and the reason is not the specification. It is the middle. Every load balancer, WAF, API gateway, CDN and corporate proxy between your client and your server has an opinion about methods it does not recognise, and a surprising number of them drop or reject unknown methods outright. A method is only usable when the path supports it end to end.

Where it is worth trying now

• Internal service-to-service APIs. You control every hop, so the middle is not a risk. This is where the caching benefit lands soonest, because internal search traffic is repetitive.
• New public endpoints, alongside POST. Advertise Accept-Query, keep the POST path, and let clients upgrade. You get real data on whether QUERY survives your users' networks.
• Anywhere a filter currently exceeds the URL. If you already base64 a JSON blob into a query string, you have the problem QUERY exists to solve and you have already accepted the migration cost once.

Where it is not worth trying: an existing high-traffic public API where POST works and nobody is complaining. The upside is cacheability you can approximate today with an application cache, and the downside is debugging a proxy in a customer's network.

How to keep the option open

If you are designing an endpoint now and QUERY is not yet viable on your path, there is a cheap way to avoid painting yourself into a corner.

Keep the filter as a self-contained document in the request body rather than spreading it across query parameters, headers and path segments. Ship it as POST today. The day QUERY becomes viable, the change is the method verb and an Accept-Query header, not a redesign of how a filter is expressed.

The teams that will find this migration painful are the ones whose filters are assembled from six different places in the request, because there is nothing to move. That is worth avoiding regardless of whether QUERY ever reaches your production path — a filter that can be serialised, logged and replayed as one object is easier to debug on any method.

Why it is worth knowing about anyway

Standards move slowly and the useful moment to understand one is before the decision, not after.

PATCH took years to become unremarkable, and teams that understood it early designed cleaner update semantics in the meantime — even on APIs that never adopted the method — because knowing that partial update was a real, separate concept changed how they modelled it. QUERY has the same character. It names something that was already true: reads with complex parameters are a distinct category, not a variant of create.

The immediate practical value is that it settles an argument. When someone proposes POST /search, the answer is no longer "it is fine, everyone does it". It is that the request is a read, POST misdescribes it, and there is now a correct method — so if you are using POST, do it deliberately, document it as a read, and stop pretending the cache headers make sense.

We design and integrate APIs for clients, and this changes a recommendation we give often. It does not change what we would ship this quarter. When we build a system with a heavy internal search path, QUERY is now on the table for the internal hops. On anything public, we are watching the gateways rather than the spec — and if you want to talk through where it fits, we are happy to.