HTTP QUERY Method: Solving Complex API Queries with RFC 10008

RFC 10008 defines the new HTTP QUERY method to provide a standardized way to perform complex read-only operations that require a request body. This solves the long-standing tension between the limitations of GET query parameters and the semantic incorrectness of using POST for data retrieval.

Why the HTTP QUERY Method is Necessary

The HTTP QUERY method is required because existing methods cannot efficiently handle complex relational queries or deeply nested data structures without compromising technical stability or API semantics.

Limitations of GET

While GET is the standard for retrieving data, it relies on query parameters in the URL. This approach fails in several scenarios:

• URL Length Limits: Complex filters can create massive URLs that exceed browser or server character limits.
• Encoding Overhead: Non-ASCII or special characters must be encoded, increasing request size.
• Security and Logging: Request parameters are often logged by servers and middleware, potentially exposing sensitive data.
• Lack of Structure: There is no universal standard for expressing arrays or deeply nested structures in a URL (e.g., ?roles[]=admin vs ?roles=admin).

The Failure of GET with Request Bodies

Although no RFC explicitly forbids a request body in a GET request, it is strongly discouraged. In practice, many clients, proxies, and web servers handle GET bodies inconsistently—some reject them outright, while others drop the body entirely. This makes GET with a body an unreliable choice for production environments.

The Semantic Issues with POST

Developers often use POST as a workaround to send a request body for queries. However, POST is defined as non-idempotent and is intended for resource creation or processing. This creates several issues:

• Retries: Because POST is not idempotent, automatic retries on failure are risky.
• Caching: Proxies and middleware cannot automatically identify POST requests as read-only, preventing the use of standard caching mechanisms.

Technical Specifications of the QUERY Method

The QUERY method is designed to be functionally similar to GET but explicitly supports a request body. Its primary characteristics include:

• Safety and Idempotency: Like GET, QUERY is defined as safe and idempotent, meaning it does not change the state of the server.
• Cacheability: QUERY requests can be cached. However, implementations must incorporate the request body into the cache key to ensure the correct data is returned for different query parameters.

Implementation Considerations and Gotchas

Despite the standardization, the QUERY method is not a drop-in replacement for all search endpoints. Developers should consider the following constraints:

• Limited Ecosystem Support: Support for QUERY is currently limited. Many proxies, firewalls, and web servers may still reject the method. For example, while the Kreya API client added support in version 1.20, widespread adoption may take years.
• Linkability: QUERY requests cannot be bookmarked or shared via a simple URL because the query parameters reside in the request body rather than the URL.
• Caching Complexity: Implementing custom caching for QUERY is more complex than for GET because the cache key must be derived from the request body.

Community Perspectives and Critiques

Discussion among engineers highlights a divide between those who value explicit standards and those who prefer following existing conventions.

Arguments for the New Method

Some argue that having an explicit method is the only correct way to move forward, as using GET with a body is a "hack" that should not be standardized.

Arguments Against the New Method

Critics suggest that the standard should have followed the existing convention of GET with a body, arguing that introducing a new verb may cause issues with legacy infrastructure. One user noted the risk of "DoS by the track record" when expensive SSL intercepting proxy appliances that only support HTTP/1.1 encounter an unknown HTTP verb.

Other developers have questioned whether adding a new method just to support a request body is the best way to maintain the long-term relevance of the HTTP specification, suggesting it may be a path of least resistance rather than a robust design.