TL;DR
HTTP just got a new method: QUERY. It landed as RFC 10008 in June 2026, after the working group chewed on it for years. Think of it as GET with a body - safe, idempotent, and cacheable, but you send your query in the request content instead of stuffing it into the URL. It kills the “should this search be a GET or a POST?” argument that every API team has had, and it does it without giving up caching. That is the exciting part.
The problem QUERY solves
For as long as REST has existed, every backend engineer has hit the same wall. You have a search or filter endpoint. The filter is complex: nested conditions, arrays, a geometry, a whole JSON blob. And you have exactly two bad options.
Option A: GET with a giant query string.
GET /contacts?name=Smith&city=Berlin&tags=vip,eu&sort=-created&fields=email,phone
GET is the “right” method semantically. It’s safe (no side effects), idempotent, and cacheable. The problem: URLs are not meant to carry a database query. You hit length limits (many proxies and servers cap around 8 KB), you fight URL-encoding for anything nested, and search logs leak your filters into access logs, browser history, and referrer headers. Try encoding a polygon or a 40-field filter into a query string and tell me how it goes.
Option B: POST with a body.
POST /contacts/search
Content-Type: application/json
{ "name": "Smith", "city": "Berlin", "tags": ["vip", "eu"] }
The body is clean. The nested JSON is happy. But you just lied to HTTP. POST means “this changes state.” It is not safe, not idempotent, and not cacheable. Now your CDN won’t cache the response, your client libraries treat retries as dangerous, and anyone reading your API thinks a search mutates something. Every team papers over this with a comment that says “yes it’s a POST but it doesn’t actually write anything, promise.”
Both options are workarounds. The protocol never had the method the job actually needed.
What QUERY is
QUERY is that missing method. From RFC 10008, a QUERY request asks the server to process the enclosed content in a safe and idempotent manner and return the result.
QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/json
Accept: text/csv
{ "name": "Smith", "city": "Berlin", "tags": ["vip", "eu"] }
HTTP/1.1 200 OK
Content-Type: text/csv
surname, givenname, email
Smith, John, john.smith@example.org
Three properties, and all three matter:
- Safe. Like GET, a QUERY does not change resource state. Intermediaries, crawlers, and clients can treat it as read-only.
- Idempotent. Send it twice, get the same result. Safe to retry after a dropped connection, which POST never guaranteed.
- Cacheable. This is the killer feature. POST-based search threw caching away. QUERY keeps it.
You get the clean body of POST and the semantics of GET at the same time. That combination did not exist before.
The caching trick
Caching a request that has a body is the hard part, and it’s why this took so long to standardize. A GET cache keys on the URL. Two requests to the same URL are the same request. But two QUERY requests to /contacts can be totally different depending on their bodies.
So the cache key has to include the request content. RFC 10008 says caches SHOULD normalize the body first to strip out meaningless differences: remove content encoding, use the media type (a +json suffix means JSON rules apply), and normalize per the content’s own semantics. So these two:
{"name":"Smith","city":"Berlin"}
{ "city": "Berlin", "name": "Smith" }
can be treated as the same cache entry even though the bytes differ. Whitespace and key order stop mattering. That is a genuinely new bit of HTTP caching machinery, and it’s what makes cacheable search actually work in practice.
There’s also an indirect flavor. The server can answer a QUERY with Content-Location pointing at a GET-able URL for the result, or send a 303 See Other with a Location and let the client fetch results separately. That gives you a stable, shareable, bookmarkable URL for a query result - something a POST search could never hand you.
Why this is exciting, not just tidy
It’s easy to shrug at “new HTTP method.” Here’s why it’s more than protocol trivia:
- It ends a real, universal design argument. GET-vs-POST for search has burned time in code review on basically every API team on earth. Now there’s a correct answer with a spec behind it.
- It makes search cacheable again. CDNs, reverse proxies, and browsers can cache expensive query results keyed on the actual query. For read-heavy APIs, that’s a performance and cost win you previously had to fake with hashed GET URLs.
- It’s honest. Your API surface stops lying about what mutates. Safe methods read; unsafe methods write. Tooling, security scanners, and humans can trust the method again.
- HTTP rarely changes. New methods are rare. The core method set has been stable for a very long time. A safe, idempotent, body-carrying method fills a gap people have worked around for two decades. When the protocol itself moves, it’s worth paying attention.
Can you use it today?
Carefully. RFC 10008 is a Proposed Standard, and support is uneven this early:
- Node.js has parsed QUERY natively since early 2024.
- OpenAPI 3.2 can document it.
- Spring support is still an open pull request as of this writing.
- Browsers, corporate proxies, old firewalls, and some SDKs will lag. Some middleboxes drop methods they don’t recognize.
Practical advice: adopt it where you control the whole path (internal service-to-service APIs, your own gateway, your own clients) and it pays off immediately. For public APIs on the open internet, offer QUERY but keep the POST fallback until the ecosystem catches up. New methods take years to reach every proxy and firewall, and “unknown method dropped by a middlebox” is a debugging session nobody enjoys.
Bottom line
QUERY is a small addition with an outsized effect. It gives HTTP the one method it was always missing: a way to send a real request body without pretending you’re changing something, and without losing caching. If you’ve ever written POST /search and felt slightly dirty about it, this is the fix you were waiting for.
Sources: RFC 10008 (RFC Editor), datatracker, IETF draft text.