RFC 10008: The HTTP QUERY Method

My notes

Summary

RFC 10008 (June 2026, IETF Standards Track) defines a new HTTP method, QUERY, that sits between GET and POST. It sends the query in the request body like POST, but is explicitly safe and idempotent like GET, so caches and automatic retries can operate on it. It solves the long-standing problem of queries too large or too sensitive to encode in the URL.

Key Insight

Why it exists - GET vs POST gap:

• GET puts the query in the URL: breaks at ~8000 octets (recommended floor), leaks into logs/bookmarks, and makes every input combination a distinct cacheable “resource”.
• POST avoids those, but a server can’t tell a POST is a safe read, so no caching, no safe auto-retry.
• QUERY = body-based input + advertised safe/idempotent semantics. That is the whole point.

Concrete mechanics worth knowing:

• Cache key MUST include the request body + metadata (Content-Type), not just the URL. Caches MAY normalize semantically-insignificant differences (strip content-encoding, +json normalization) purely to build the key, never altering the actual request.
• Accept-Query response header advertises which media types a resource accepts for QUERY (uses Structured Fields syntax, RFC 9651, not the same parser as Accept). Discoverable via OPTIONS (Allow header) too.
• Location / Content-Location let the server hand back a plain URL for the result or the “equivalent resource”, so clients can switch to cheap conditional GETs (ETags, 304 Not Modified) and stop resending the body.
• Status code map is precise: missing media type to 400; type unsupported to 415; type ok but content malformed to 400 (no content-sniffing allowed); syntactically valid but unprocessable (e.g. SQL hitting a non-existent table) to 422; unacceptable response type to 406.

Two practical gotchas:

• CORS: QUERY is not a safelisted method, so browsers will always send a preflight OPTIONS.
• Redirect quirk: the POST to GET downgrade on 301/302 does not apply to QUERY, it stays QUERY to the new target.

Naming trivia: “SEARCH” (WebDAV, RFC 5323) was the early candidate but was dropped, the WG wanted to avoid WebDAV baggage and a generic application/xml body. QUERY ties cleanly to the URI query component.