The problem with GET and POST

Queries have traditionally been sent as GET requests with URL parameters (/feed?q=foo&limit=10). That works until the query grows: URLs hit undocumented length limits across proxies and CDNs, encoding complex data into a URI is inefficient, and query parameters end up in server logs, browser history and bookmarks — often not where you want your search terms.

The common workaround is POST with the query in the request body. But POST officially means "this request may change state". Caches will not cache it, clients must not retry it automatically after a connection failure, and no intermediary can tell that your POST is actually a harmless read.

What QUERY does differently

QUERY combines the best of both: like POST it carries the query in the request body, but the specification defines it as safe, idempotent and cacheable — exactly like GET. A QUERY request looks like this:

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

Because QUERY is explicitly safe and idempotent, infrastructure can finally cooperate:

• Clients and proxies may retry a failed QUERY automatically — there is no risk of a duplicate side effect.
• Caches may store and reuse QUERY responses; the request body becomes part of the cache key.
• Conditional requests work: servers can return ETags and answer repeated queries with 304 Not Modified.
• Servers can assign URIs to a query or its result via the Location and Content-Location headers, so results stay addressable with plain GET.

Strict rules for servers

The RFC is deliberately strict about error handling. A QUERY request without a Content-Type header must be rejected with a 4xx status — servers are not allowed to guess ("sniff") the format. An unsupported media type should get a 415 Unsupported Media Type, ideally together with the new Accept-Query response header, which advertises the query formats a resource understands. A query that is well-formed but cannot be processed (say, an SQL query referencing a missing table) should return 422 Unprocessable Content.

Try it yourself

Support in frameworks and servers is just starting to appear, which makes testing tools valuable. We built a free HTTP QUERY Tester that sends QUERY requests to any endpoint from your browser (via a server-side relay, since browsers cannot send QUERY cross-origin yet) and runs an automated RFC 10008 compliance report: Does the server reject missing Content-Types? Does it answer unsupported formats with 415 and Accept-Query? Does it return cache validators?

It comes with a public, fully RFC-conforming echo endpoint at onlinetoolhub.dev/api/query-echo — including all error cases, ETag/304 support and CORS — so you can develop QUERY clients against a known-good server. Or try it from your terminal right now:

curl -X QUERY https://www.onlinetoolhub.dev/api/query-echo \
  -H "Content-Type: application/json" \
  -d '{"q": "hello", "limit": 5}'

Should you adopt it?

If you control both client and server and your "queries via POST" endpoints are actually side-effect-free, QUERY is a clean upgrade: you gain retries, caching and clearer semantics for free. For public APIs, expect a transition period — older proxies may not know the method, so offering QUERY alongside an existing POST endpoint is a pragmatic path. Either way, it is worth understanding now: safe-methods-with-body has been one of the longest-standing gaps in HTTP, and RFC 10008 finally closes it.

Further reading: the full specification at datatracker.ietf.org including examples for discovery, redirects and conditional requests.