By ByteBot
The IETF published RFC 10008 this week, standardizing a new HTTP method called QUERY — and if you’ve ever had to POST to a read-only endpoint because your query was too large for a URL, this one’s for you. QUERY sends the query payload in a request body, exactly like POST, but tells every client, server, proxy, and CDN in the chain that the operation is safe and idempotent. Responses are cacheable. Retries are automatic. It’s the HTTP QUERY method that should have existed a decade ago.
Why GET and POST Both Fail for Complex Queries
GET is the right method for read-only queries. It’s safe, idempotent, and cacheable — every property you want from a query operation. However, GET doesn’t carry a request body. All query data has to fit in the URL, and URLs have limits: browsers cap somewhere between 2,000 and 8,000 characters depending on implementation, and intermediaries are even less predictable. When query parameters get complex — multi-field filters, deeply nested criteria, long search strings — GET breaks down.
POST fills the gap, but at a cost. POST supports a request body, so developers have been using it for large queries for years. The issue is that POST carries no safe-or-idempotent guarantee. From a cache’s perspective, POST is a black box — the response can’t be cached, the request can’t be automatically retried, and the semantics imply state mutation even when none is happening. GraphQL uses POST for all query operations for exactly this reason: it needs a body. The result is that every GraphQL query — explicitly read-only by design — loses HTTP-level caching and auto-retry safety. Developers work around this with persisted queries, CDN-specific POST caching rules, and other workarounds. It’s inelegant, and it’s the kind of thing that accumulates invisible operational debt.
How the HTTP QUERY Method Works
QUERY takes the body flexibility of POST and attaches the semantics of GET. A QUERY request carries its payload in the body, just like POST, but the RFC explicitly marks it as safe and idempotent. Caches can store the response. Clients and proxies can retry the request automatically on failure. The cache key includes both the URL and the request body — which makes caching more complex than GET, but the spec accounts for this and allows normalization of semantically insignificant differences (whitespace, encoding) to improve cache hit rates.
Here’s what a basic QUERY request looks like:
QUERY /contacts HTTP/1.1
Host: api.example.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
select=surname,givenname,email&limit=10The server responds with 200 OK and the query results, or 303 See Other with a Location header pointing to a cached result resource. The latter pattern is particularly useful for CDNs: the result gets stored at a stable URL that can be cached and served like any GET response. The RFC also defines an Accept-QUERY header that servers use to advertise which query formats they support.
What Changes for GraphQL and REST APIs
The most immediate beneficiary is GraphQL. Today, all GraphQL operations route through POST, including queries that touch no mutable state. With QUERY standardized, the GraphQL Foundation has a clean path to shift query operations to QUERY — preserving HTTP-layer caching and retry semantics without any changes to the query language itself. Whether the Foundation moves on this is a separate question, but the blocker is now gone.
For REST APIs, the impact is on complex filter and search endpoints. If you’ve built an endpoint that accepts a JSON filter body over POST because URL encoding was too unwieldy — search facets, aggregation pipelines, multi-condition filters — QUERY is the semantically correct replacement. It signals to every layer of your infrastructure that this is a read operation, enabling caching configurations that POST simply can’t support. According to Nordic APIs, the QUERY method “splits the difference between GET and POST,” carrying body payloads while making it explicit that an idempotent query is happening.
Adoption: What Still Needs to Happen
RFC 10008 is a finalized standard, not a shipping feature. Actual adoption requires updates across the entire stack: HTTP client libraries (curl, fetch, axios), server frameworks (Express, FastAPI, Django, Spring), and CDN caching engines. The fact that Cloudflare’s James Snell and Akamai’s Mike Bishop co-authored the spec is a meaningful signal — both companies are positioned to ship CDN-level QUERY support earlier than most framework integrations. Browser fetch() support requires WHATWG action, and that will take time.
The HTMX community already has an open GitHub discussion asking whether QUERY can be used — early evidence that developer interest exists well before tooling catches up. The spec is clean and well-reasoned. What developers should do now: read the RFC, watch for framework support announcements, and identify existing POST-for-query endpoints in your API that could be refactored once support lands.
Key Takeaways
- RFC 10008 standardizes the HTTP QUERY method: safe, idempotent, cacheable, and body-capable — no existing HTTP method combined all four properties before now
- GraphQL’s use of POST for read-only queries is the most visible problem QUERY solves; the spec gives the Foundation a clean migration path without changing the query language
- REST APIs with complex filter payloads currently using POST — and losing cache benefits — have a semantically correct alternative once frameworks ship support
- Cloudflare and Akamai co-authored the RFC, suggesting CDN-level support may arrive ahead of framework integrations
- The spec is final; watch curl, browser fetch(), and your server framework for QUERY implementation announcements over the coming months
