RFC 10008 Adds a QUERY Method to HTTP

For years, anyone building a search endpoint has faced the same awkward choice. Cram every filter into a URL and risk blowing past length limits, or POST the criteria as a body and quietly surrender the guarantees that make GET pleasant to work with — caching, retries, and a clear signal that nothing on the server is going to change. RFC 10008, "The HTTP QUERY Method," closes that gap with a new verb that carries a request body while remaining explicitly safe and idempotent.

Authored by Julian Reschke, James Snell, and Mike Bishop, the document is on the IETF Standards Track as a Proposed Standard, having cleared IESG review and IETF consensus. It registers both the QUERY method and a companion Accept-Query header field with IANA.

The problem QUERY is built to fix

The canonical search request looks like this:

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

Clean, cacheable, and bookmarkable — until the input no longer fits comfortably in a URI. The RFC enumerates why that pattern breaks down at scale:

• Length limits are unpredictable because a request may traverse many uncoordinated intermediaries. The HTTP core spec only recommends support for at least 8000 octets.
• Encoding structured data into a valid URI is inefficient and lossy.
• Request URIs tend to land in logs and bookmarks far more readily than request bodies.
• Treating every combination of inputs as a distinct URI fragments the resource space.

The usual escape hatch is POST:

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

q=foo&limit=10&sort=-published

This is the shape of countless real-world APIs — GraphQL endpoints, Elasticsearch's _search, and any number of "send me a JSON filter" services lean on POST precisely because the criteria are too big or too structured for a URL. The cost is semantic: as the RFC notes, without out-of-band knowledge of the server, there is no way to tell that a POST is a read-only query rather than something that mutates state. Caches treat it as opaque, and clients can't safely retry it.

How QUERY behaves

QUERY puts the input in the body, like POST, but pins down its semantics, like GET:

Advertisement

Shadow GPS — know where it is, always Real-time GPS tracking for vehicles, gear and loved ones. No monthly contracts.

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

Because the method is defined as safe and idempotent, an intermediary or client library can repeat or restart the request "without concern for partial state changes," in the spec's words. That property is what unlocks automatic retries and caching for body-bearing queries — neither of which is sound over POST.

The RFC's own summary table is the clearest way to see where the new method sits:

Two response fields do the heavy lifting for the "every important resource deserves a URI" principle. A server can return a Location that names the query itself — a GET-able URL that re-runs the same search — and a Content-Location that names the specific result representation. That turns an expensive body-driven query into something a client can bookmark, share, or fetch with a plain GET later.

Caching, conditional requests, and content negotiation

The interesting engineering lives in the details the spec spends most of its sections on. Caching QUERY responses is not a free lunch: HTTP caches are keyed on the request URI, and QUERY smuggles its variance into the body. The RFC devotes explicit sections to caching, conditional requests, range requests, and redirection — meaning a compliant cache has to account for the request content, not just the method and URL, when deciding what a stored response is keyed to. That is precisely the kind of subtlety that has historically made body-aware caching hard, and it's the part CDN and proxy implementers will want to read most carefully.

Discovery gets first-class treatment too. The new Accept-Query header field lets a resource advertise which media types it will accept as query content, so clients can negotiate formats rather than guess. Content negotiation on the request side mirrors the familiar Accept mechanism on the response side.

What it means for framework and API authors

A new HTTP method is a slow-moving change by nature — it has to propagate through clients, servers, proxies, load balancers, and the long tail of middleboxes that may simply drop a verb they don't recognize. None of that happens overnight, and the safe-and-idempotent guarantees only hold if every hop honors them.

Still, the direction is set, and the practical to-do list is concrete:

• Routing layers will need to recognize QUERY as a distinct method rather than coercing it into GET or POST handlers.
• Caches and CDNs must decide how — and whether — to key stored responses on request content, the thorniest part of the design.
• Client libraries and SDKs can begin treating QUERY failures as retry-eligible, the way they already do for GET.
• API designers finally get a standards-blessed way to express "this is a read," without overloading POST or stuffing JSON into a query string.

The value here is honesty in the protocol. For a decade, "POST that's really a read" has been an unwritten convention that tooling couldn't reason about. RFC 10008 writes it down — and gives the safe, repeatable query a name of its own.