Vivek's Blog

If you have ever built a search API and asked yourself "should this be a GET or a POST", you already know the pain I am about to talk about. On June 15, 2026, the IETF published RFC 10008, and it defines a brand new HTTP method called QUERY. This is the first new HTTP method since PATCH back in 2010. That is a sixteen year gap, so yeah, this is a genuinely big deal for anyone writing APIs.

The old problem: GET vs POST for search

For years we only had two real options when we needed to fetch data based on some filter or search criteria.

Option 1: GET with query params

GET /api/v1/users?role=admin&status=active&sort=desc

This works fine for simple stuff. But the moment your filters get complex (nested conditions, long lists, full text search strings), things fall apart fast:

• URLs have practical size limits, and browsers/proxies do not agree on what that limit even is
• Every unique combination of filters becomes its own "resource" from a caching point of view, which is messy
• Query strings show up in server logs and browser history, so anything sensitive in there is now sitting in plaintext somewhere
• Encoding complex objects (nested JSON, SQL-ish filters) into a URL is just ugly and error prone

Some people tried sending a GET with a JSON body to get around the size limit. Technically nothing in the HTTP spec forbids this, but in practice browsers, proxies, and servers all handle it differently. Some strip the body, some reject it outright. So it never became reliable enough to use in production.

Option 2: POST as a workaround

POST /api/v1/users/search
Content-Type: application/json

{ "role": "admin", "status": "active", "sort": "desc" }

This solves the body size problem, but it introduces a new one: POST does not tell anyone that this is a read only, safe operation. A POST could create a user, trigger a job, charge a credit card, anything. So:

• Caches will not touch it, because caching a POST response is dangerous by default
• Automatic retries are not safe either, since the spec has no guarantee the operation is idempotent
• CDNs and reverse proxies just treat it like any other write

Basically we were choosing between "safe but cramped" (GET) and "flexible but untrustworthy" (POST). Neither one was actually correct for the "search with a big payload" use case, and everyone just picked whichever pain they could live with.

The fix: QUERY

QUERY takes the request body from POST and combines it with the safe, idempotent, cacheable guarantees of GET. That is really the whole idea.

QUERY /users HTTP/1.1
Host: example.org
Content-Type: application/json

{
  "role": "admin",
  "sort": "name",
  "page": 1
}

Because QUERY is explicitly defined as safe and idempotent in the RFC, this unlocks a bunch of things that were never reliably possible with POST-as-search:

• Caching: proxies and CDNs can now cache the response, using the request body plus content type as part of the cache key (not just the URL)
• Safe automatic retries: if the network drops mid request, clients can just resend it without worrying about creating duplicates or corrupting state
• Clear semantics: middleware, firewalls, and API gateways can finally tell "this is a read" without guessing based on the endpoint name

There is also a new response header called Accept-Query, which lets a server advertise that it supports QUERY and which content types it accepts for the query body:

Accept-Query: "application/json", "application/sql"

Since QUERY is format agnostic, the RFC does not force a specific query language on you. You can send JSON filters, SQL-like expressions, JSONPath, GraphQL, whatever your resource wants to accept and interpret.

Bonus feature: stored queries

One of the more clever parts of the spec is that a server can respond to a QUERY with a Location or Content-Location header pointing to an equivalent resource. That means once the server has run your complex query, it can hand you back a plain URL you can hit with a regular GET later, without resending the whole query body again.

QUERY /rfc-index.xml HTTP/1.1
Host: example.org
Content-Type: application/sql
Accept: text/csv

SELECT * FROM rfcs WHERE status = 'active'

Server responds:

HTTP/1.1 200 OK
Content-Type: text/csv
Location: /stored-queries/4815162342
Accept-Query: "application/sql"

Now you (or anyone you share the link with) can just do:

GET /stored-queries/4815162342 HTTP/1.1
Host: example.org

and get fresh results every time, using normal GET caching and conditional requests like If-Modified-Since. Basically you get a bookmarkable, shareable, cacheable search, which was never really possible before.

Should you use it right now

Technically? Sure, the spec is final and it is a Proposed Standard. Practically, adoption is going to take a while. Every framework, proxy, CDN, API gateway, and client library needs to add support for a brand new HTTP method, and that kind of rollout historically takes years, not months. Cloudflare and Akamai co-authored the RFC though, so CDN level support might show up before your favorite backend framework gets around to it.

If you are building an RPC style API where a lot of your "POST" endpoints are secretly just reads with complex filters (search, analytics, reporting, vector search, anything like that), this is worth keeping an eye on. It is the cleanest fix HTTP has gotten for this problem in a long time.