Introducing HTTP QUERY
Unless your name is Patrick Star and you live under a rock, you've probably heard about the newly standardized HTTP QUERY method (RFC 10008). I've seen about 3-4 articles or posts referencing it so far, but nothing comprehensive.
RFC 10008 formally defines QUERY as a new HTTP method for safe, read-only requests that need more structure than a plain URL query string can conveniently support. The idea is not to replace GET or POST, but to give read-heavy APIs a more precise choice when neither of the older methods is suitable for the situation.
HTTP method choice affects many things; safety, idempotency, retry behavior, caching, and how clients, proxies, and gateways should interpret the request. Here are the semantics of QUERY as defined in Section 2 of RFC 10008, and how it stacks up to other methods.
How QUERY Differs from GET and POST
| Method | Primary role | Safety1 / idempotency2 | Body support3 |
|---|---|---|---|
| GET | Simple retrieval | Safe + idempotent | Usually no body; inputs in the URL |
| QUERY | Structured read-only lookup | Safe + idempotent | Body-capable for richer criteria |
| POST | Actions and submissions | Not safe by default | Body-capable, but not read-only |
- Safe: the request is intended to read data without changing server state.
- Idempotent: repeated identical requests leave the server in the same end state as a single request.
- Body: the method can accept structured input in the request body instead of URL parameters.
Why This New Method Was Necessary
In practice, teams often stretch GET past its intended use once filter sets get large, nested, or too complicated for a query string. The common workaround is to switch to POST, since it accepts a body, but that complicates the request when the intention is actually read-only. QUERY exists to bridge the gap, allowing reads to utilize a body without sacrificing their safety guarantees.
This is a significant change, which will likely take years to be adopted and see in the wild. QUERY changes how we think about requests, and provides a clean mechanism for read-only operations with many criteria, in an age where data is increasingly complex and interconnected.
Takeaways from the official RFC:
- QUERY is meant to be used for complex, read-only requests.
- Send a valid Content-Type on QUERY request bodies.
- Handle negotiation errors like 415 and 406; reject unsupported request Content-Types with 415, and unsatisfiable Accept headers with 406.
- Expect CORS preflight for browser-based QUERY calls.