TL;DR / Key Takeaways
- A new HTTP method called QUERY is here to fix the broken way we handle complex searches.
- It finally ends the abuse of POST for read-only APIs.
The Semantic Sin We All Committed
For decades, retrieving data often meant encoding search parameters directly into a GET request's URL query string. This approach quickly faltered with complex searches involving relational queries or deeply nested data. URLs ballooned, frequently hitting browser or server length limits, and exposing all parameters plainly in server logs and browser history.
To circumvent URL constraints, developers adopted a workaround: using POST requests to carry intricate search filters within the request body. This, however, created a significant semantic violation. `POST` is fundamentally designed for creating new resources, not for the safe, idempotent retrieval of existing data.
Misusing `POST` for search carried tangible consequences. It broke caching mechanisms, as proxies rarely cache `POST` responses due to their non-idempotent nature. Furthermore, its non-idempotent characteristic prevented clients from safely performing automatic retries on network failures, a fundamental capability of truly read-only operations.
A less common, but equally problematic, attempt involved sending a request body with a `GET` method. While the HTTP/1.1 specification ambiguously permitted this, it explicitly stated that such a body held "no defined semantics" and "SHOULD be ignored." This rendered "GET with a body" an unreliable, non-standardized myth, never gaining consistent support across the web's infrastructure.
QUERY: GET's Safety, POST's Power
Finally, the HTTP query method (RFC 10008) arrived, formally standardized in June 2026. It represents the "missing method for search," purpose-built to address the semantic workarounds developers have used for over two decades. This new verb specifically targets complex, read-only data retrieval.
Query elegantly combines the best attributes of its predecessors. Like GET, it is safe and idempotent, meaning it never alters server state and identical requests consistently yield the same result. This property enables robust client retries on failures. Crucially, like POST, it accepts a request body, providing ample space for query parameters.
This hybrid design directly solves the core problem of rich data retrieval. Developers can now send intricate, deeply nested query structures, such as JSON payloads, within the request body. This avoids hitting browser or server URL length limits and prevents exposure of sensitive parameters in logs. Critically, it eliminates the semantic violation of using POST for non-state-changing operations, finally providing a standardized, cacheable, and semantically correct approach for advanced API searches.
Smarter Caching, Better Security
`QUERY` brings significant operational advantages beyond semantic correctness, particularly in caching and security. Its design addresses long-standing challenges that plagued `GET` and `POST` in complex data retrieval scenarios.
Responses generated by a `QUERY` method are fully cacheable, mirroring `GET`'s efficiency. Critically, the entire request body factors directly into the cache key. This sophisticated mechanism guarantees that each unique query body, regardless of the URI, yields a distinct cache entry, facilitating precise and efficient data retrieval.
A built-in discovery mechanism further enhances `QUERY`'s utility: the `Accept-Query` header. Servers can now explicitly advertise the specific query formats they support, streamlining client-server communication and improving API discoverability. Clients gain clarity on expected syntaxes, reducing integration friction.
Security and privacy also see marked improvements. `QUERY` is not a CORS-safelisted method, requiring a preflight `OPTIONS` request for cross-origin calls and bolstering web application security. More importantly, it keeps sensitive query parameters out of URLs, preventing their exposure in server logs, proxy records, and browser history, a significant privacy win over `GET`.
This careful design makes `QUERY` a robust solution for modern API needs. For deeper technical specifications, refer to RFC 10008: The HTTP QUERY Method, which details its full capabilities and implications for web architecture.
Enjoying this? Get one like it in your inbox each morning.
one email a day · unsubscribe in two clicks · no third-party tracking
The Road to Adoption: A Reality Check
QUERY (RFC 10008) is now formally standardized, a critical step forward for HTTP semantics. Despite this foundational achievement, widespread adoption across the entire web ecosystem remains in its early stages. Browsers, diverse web frameworks, and network proxies are progressively rolling out their support for this new method, a process that takes time for a fundamental protocol change.
Momentum is clearly building, with key players already integrating `QUERY` into their platforms. OpenAPI 3.2 now formally supports the `QUERY` method, allowing architects and developers to define these powerful new endpoints directly within their API specifications. Microsoft's .NET 10 framework also provides initial, robust support, indicating a strong signal for broader framework integration and encouraging early experimentation.
Organizations should strategically plan for `QUERY`'s eventual omnipresence. For new, complex read-only endpoints, design with `QUERY` from the outset, but implement robust fallbacks to `POST` or `GET` for compatibility. Finally, prepare to update existing web application firewalls (WAFs) and proxy configurations; these systems must learn to correctly interpret, route, and cache `QUERY` requests for seamless operation.
Frequently Asked Questions
What is the new HTTP QUERY method?
It's a new, standardized HTTP verb (RFC 10008) designed for complex search and data retrieval. It combines the safety and cacheability of a GET request with the ability to carry a request body like a POST request.
Why not just use GET with a request body?
The behavior of a GET request with a body is undefined in the HTTP specification. This leads to inconsistent and unreliable handling by servers, proxies, and caches, making it an impractical solution.
Is the QUERY method ready for production use?
Not yet for most applications. While it is officially standardized, widespread support across browsers, server frameworks, and infrastructure like proxies and WAFs is still in the early stages.
How does QUERY improve caching over using POST for search?
POST responses are generally not cached by intermediaries like proxies or CDNs. QUERY responses are explicitly designed to be cacheable, with the request body's content used as part of the cache key, significantly improving performance.