# RFC 10008: The HTTP QUERY Method

> RFC 10008 defines the HTTP QUERY method: a body-based request that is safe and idempotent like GET, so caches and retries work for large queries.

Published: 2026-06-15
URL: https://daniliants.com/insights/rfc-10008-the-http-query-method/
Tags: http, rest-api, api-design, web-standards

---

## 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.