Card 07/ 10
QUERY: A Safe Method That Carries a Body
A search too large for a URL used to need POST; QUERY carries it in a body and stays safe to repeat.
QUERY is an HTTP method for reads whose input is too large or too structured for a URL. Like POST it sends its input in the body, and like GET it is safe and idempotent, so caches may store its response and clients may retry it. It was standardised in RFC 10008 in June 2026, so support in servers, proxies and client libraries is still arriving.
Picture a product search with forty filters: price ranges, a list of brands, nested conditions. Encoded into a query string it runs to thousands of characters, past the URL length some servers and proxies accept.
POST /products/searchnot safe, not idempotent
The body carries the filter. Caches will not store the result, a retry library will not resend it after a timeout, and nothing tells a client or proxy that the call only reads.
QUERY /productssafe and idempotent
The same body. A cache may store the result, keyed on the body as well as the URL, and a client may resend it freely after a timeout, because the method promises it only reads.
Why GET does not solve it. HTTP gives a GET body no defined meaning. It is not forbidden, but servers, proxies and client libraries may drop it, reject it or ignore it, so an API cannot rely on one arriving.
Why URLs are limited. The HTTP standard sets no maximum length, but recommends supporting at least 8,000 characters, and many servers, proxies and CDNs reject longer ones. Long URLs also end up in logs and browser history.
What QUERY adds. The request's Content-Type says how to read the body, for example JSON. The server may answer with the results, and may also give the query its own URL in a Location header, so a client can repeat it later with a plain GET.
What to do today. Where every component on the path supports QUERY, use it for large reads. Where they do not yet, POST to a search resource remains the practical fallback; document it as a read, and do not retry it automatically unless the server says it is safe.
So QUERY fills the gap between GET and POST: a body like POST, with the promises of GET.
← → move through sections and cards