Desiderantes Blog

I’ve been following the evolution of the HTTP QUERY Method (RFC 10008) since it was still a draft. Around 2024, after needing such a method several times at work, I started tracking its progress closely. Since then, it has recently reached Proposed status, and I’ve contributed a few pull requests implementing it. As more projects and developers have begun adopting it, I decided to keep an up-to-date GitHub Gist documenting the current state of implementations.

Every time I’ve proposed adding support for the HTTP QUERY method, the discussion has tended to revolve around the same concerns. Since I’ve found myself answering the same questions over and over, I decided to collect the most common objections here for future reference.

1. “RFC 10008 is only in Proposed status. Doesn’t that mean it’s effectively dead?”

Not really. Proposed simply means the RFC has not yet reached widespread adoption. Many successful RFCs spent years in this stage (HTTP/2 is a well-known example). An RFC being Proposed says very little about its technical merit or its eventual success.

2. “QUERY is useless for REST, so it has no value.”

REST is only one architectural style, and there is an entire world of HTTP APIs outside of it. Even if QUERY were of little value to strictly RESTful APIs, that would hardly make it useless.

That said, I’m not convinced QUERY is fundamentally at odds with REST in the first place. Roy Fielding’s dissertation, from the year 2000, understandably couldn’t account for an HTTP method that didn’t exist at the time. Meanwhile, many APIs that describe themselves as RESTful already use GET both for retrieving individual resources and for expressing complex searches over collections through increasingly elaborate query parameters.

For example, it’s common to see endpoints like:

• GET /api/orders/{id} to retrieve a specific order.
• GET /api/orders?status=shipped&customer=123&sort=date&page=2 to perform a query over a collection.

I’d argue that these are fundamentally different operations. Reserving GET for retrieving representations of specific resources while leaving QUERY for complex searches over collections results in a cleaner and more expressive API.

3. “QUERY means URLs won’t be shareable!”

Not at all. Shareable and bookmarkable URLs have always been based on GET requests, and that isn’t changing.

You can’t meaningfully share a POST, PUT, PATCH, DELETE, HEAD, or OPTIONS request by copying a URL, because the URL alone doesn’t capture the semantics of the request (and it has no body). The HTTP method, headers, and, in many cases, the request body are all part of what defines the operation. The same is true for QUERY.

In practice, resources continue to be retrieved through GET, making them just as shareable and bookmarkable (not sure it this is an actual word) as before. I’ll repeat myself here,QUERY is intended for expressing complex searches that don’t fit naturally into a URL’s query string, not for replacing GET.

If a query produces a result worth sharing, the server can always expose that result as a resource with its own GET URL, just as many applications already do today.

4. “QUERY will make it easier for websites to track users because request parameters are sent in the body.”

This concern assumes that QUERY enables something that websites can’t already do. It doesn’t.

Websites that want to send analytics or tracking information already use POST requests, often with JSON payloads containing far more information than could ever fit in a query string. Introducing QUERY doesn’t change that in any meaningful way.

As a matter of fact, QUERY would be a poor fit for analytics. Once again, the method is intended for safe, idempotent retrieval operations (non-trivial queries!!!), not for recording events or transmitting telemetry. Tracking endpoints are almost always side-effecting operations, as you want to log the tracking data, making POST the appropriate choice.

As for visibility, modern browser developer tools already display request bodies for all HTTP methods, a QUERY request body would be no different. If you’re inspecting the Network tab of your Developer tool, you’ll be able to see the method, headers, and request payload just as you do today.

5. “I can already do this with POST, or even send a GET request with a body. What’s the point?”

I mean, it’s true that you can use either approach, but both come with significant drawbacks.

Sending a body with GET is outside the semantics defined by the HTTP specification. While the spec doesn’t directly forbid it, it also doesn’t define any meaning for a request body on GET. Because of that, many intermediaries, including proxies, gateways, and frameworks, will either ignore or discard the body entirely. It’s not rare for a request to leave the client with a body and arrive at the server without one.

Using POST avoids that interoperability problem, but it introduces another one: you’re using a method whose semantics imply that the request may have side effects. Even if your endpoint is purely read-only, intermediaries, caches, browsers, and load balancers can’t safely assume that. As a result, you lose many of the benefits associated with safe methods, including straightforward caching and optimizations that infrastructure can apply automatically, like redirecting to a read-only instance, or discriminating its metrics from other unsafe requests.