HTTP QUERY Method Finally Solves the Read-Only Request Body Problem

RFC 10008 finally introduces the QUERY method for HTTP, a safe and idempotent way to send request bodies on read operations. After decades of stuffing complex filters into GET query parameters or abusing POST for searches, we now have a method that matches the semantics engineers always wanted.

Why GET and POST Fail for Complex Queries

GET requests work fine for simple filters like /api/v1/users?role=admin. But throw in deep nesting, arrays, or non-ASCII characters and you hit URL length limits, encoding headaches, and wildly inconsistent behavior across proxies and firewalls. The HTTP specs never explicitly banned a GET request body, but they strongly advise against it. Real implementations handle GET bodies differently: some reject them, some silently drop the body, others interpret it. Relying on that is a non-starter for any production system.

POST lets you send a request body, but it carries the wrong semantics. POST is non-idempotent, meant for resource creation or processing. That kills automatic retry logic (retrying a POST might double-create an entity) and prevents proxies from caching the response. Middleware that caches GET responses for performance will never touch a POST response, even when the operation is read-only.

What the QUERY Method Actually Does

The QUERY method is essentially GET with a mandatory request body. It must be safe (no side effects on the server) and idempotent. That means you can retry failed QUERY requests without fear, and proxies can cache the responses as long as they include the request body in the cache key. The RFC makes caching possible, but implementors must be careful: two QUERY requests with different bodies should not return the same cached response.

Kreya added out-of-the-box support in version 1.20, but that is a boutique gRPC client, not a browser or enterprise proxy. Widespread adoption will take years.

The Real-World Gotchas You Can't Ignore

Do not rush to migrate all your search endpoints. Standard GET queries with URL parameters are still perfectly fine for simple cases. If your users need to share or bookmark search results, stick with GET: there is no way to share a QUERY request via a URL because the body is not part of the URI.

Caching QUERY responses is harder than caching GET responses. You must hash the request body and incorporate it into the cache key, which adds complexity to reverse proxies and CDN configurations. Most existing infrastructure (Varnish, nginx, CloudFront) does not support this out of the box today.

Support for the QUERY method is extremely limited. Expect corporate firewalls, load balancers, and older web servers to reject anything that is not GET, POST, PUT, DELETE, or PATCH. Rolling out QUERY too early will break users behind strict network policies.

Plan your API schema now to allow QUERY later, but keep GET and POST fallbacks in place. The method is sound, but the ecosystem will lag behind the RFC by at least a few years.

Source: The new HTTP QUERY method explained
Domain: kreya.app