HTTP finally has a safe method with a body: QUERY

Query endpoints have been stuck between two bad options: GET cannot express a complex query, and POST describes the wrong semantics.

The IETF HTTP working group published a draft in November 2025 (draft-ietf-httpbis-safe-method-w-body-14) defining a new method: QUERY. The one-line summary:

A QUERY asks the target resource to process the enclosed content in a safe and idempotent manner and respond with the result. It is similar to POST, but can be automatically repeated or restarted without worrying about partial state changes.

The problem: queries squeezed into a URL

GET gets the semantics right — it is safe, idempotent, cacheable, and proxies may retry it freely. But its parameters can only live in the URL:

• A search with a dozen filters easily reaches thousands of characters and hits the various 8 KB ceilings
• URLs land in access logs, Referer headers, and browser history — and query filters often contain things that should not be recorded
• Nested structures (graph queries, boolean expression trees) become unreadable once flattened into a query string

The standard answer is “then use POST”. But POST means “this request may change state”, so:

• Proxies, CDNs, and client HTTP libraries will not retry it by default — one network blip means a human clicks again
• Caching layers do not know whether they may cache it
• An idempotent read gets labelled non-idempotent, purely because the vocabulary is missing a word

What QUERY fills in

The draft is deliberately modest about its scope: not a new capability, but a semantically correct method for queries that carry a body.

	GET	POST	QUERY
Request body	should not	yes	yes
Safe (no state change)	yes	no	yes
Idempotent	yes	no	yes
May be replayed automatically	yes	no	yes

Those last two rows are the entire basis on which an intermediary decides whether it may retry. QUERY brings them back while keeping the body.

Discussion happens on the ietf-http-wg@w3.org list, with source and issues under the query-method label in the httpwg/http-extensions repository. This revision expires on 22 May 2026 — which is to say it is still moving, so do not write production code against it.

Who actually needs this

Search services. Elasticsearch’s _search has accepted a GET with a body for years — a non-standard workaround everyone quietly agrees on. It works, at the cost that any strictly conforming intermediary may drop the body. QUERY makes that arrangement legitimate.

GraphQL. It is always POST, because the query itself can be large. GraphQL also has mutations, so you cannot switch the whole surface — but you can switch the read-only part, which is exactly the part carrying the most traffic.

Any RPC-style read endpoint. If the arguments are structured enough to need JSON, and the operation is read-only, POST is lying.

The friction is real

Correct semantics do not mean you can use it tomorrow. Three obstacles:

1. Intermediaries must recognise the method. Older proxies, WAFs, and some CDNs answer an unknown method with 405. They will not make an exception because your endpoint is semantically right.
2. It triggers a CORS preflight. QUERY is not a simple method, so cross-origin calls pay an extra OPTIONS round trip.
3. Browser and client library support is uneven. fetch passes any method through, but the wrappers around it (axios, requests, Go’s http package) do not all treat non-standard methods alike.

Where I land

QUERY’s value is not that it enables something new. It is that it stops an existing practice from depending on an unwritten agreement.

I would not make it the only entry point of a public API today — the 405 risk is genuine. But between internal services, or anywhere I control both ends and the middle, it is more honest than POST.

Two signals worth watching: the draft becoming an RFC, and mainstream reverse proxies allowing it by default. Until then, knowing about it beats rushing to adopt it.