For years, developers have faced the same dilemma when implementing complex search APIs:
- GET is the correct semantic choice for read-only operations, but query parameters can become extremely long and difficult to manage.
- POST allows sending a request body, but it's intended for operations that may change server state, making it a poor semantic fit for searches.
To bridge this gap, the IETF has introduced a new HTTP method: QUERY (RFC 10008).
Why was QUERY introduced?
Modern APIs often require complex filtering:
- nested JSON filters
- GraphQL-like requests
- advanced search criteria
- large lists of IDs
- geospatial or analytical queries
Encoding all of this into a URL is cumbersome and can exceed practical URI length limits. Developers have traditionally worked around this by using "POST" for read-only searches.
The problem is that "POST" doesn't express the intent of the request very well.
The new QUERY method solves this by allowing clients to send a request body while keeping the operation explicitly safe and idempotent.
Key benefits
✅ Request body support
Unlike "GET", "QUERY" allows sending structured request data in the message body, making complex searches much easier to model.
✅ Safe by design
Like "GET", a "QUERY" request must not modify server state. It clearly communicates that the request is read-only.
✅ Idempotent
Repeating the same "QUERY" request produces the same result without additional side effects, allowing clients and intermediaries to safely retry requests after transient failures.
✅ Cache-friendly
Unlike the common "POST"-for-search pattern, "QUERY" is designed to work with HTTP caching, enabling better performance and more efficient network usage.
✅ Better API semantics
Instead of overloading "POST" for read operations, APIs can now express their intent more accurately:
- "GET" → simple resource retrieval
- "QUERY" → complex read operations with a request body
- "POST" → operations that create or modify state
Example
Instead of forcing everything into a long URL:
GET /products?category=laptops&brand=Lenovo&priceMin=1000&priceMax=2500&features=..
you can send:
QUERY /products
Content-Type: application/json
{
"category": "laptops",
"brand": "Lenovo",
"price": {
"min": 1000,
"max": 2500
},
"features": [
"32GB RAM",
"OLED"
]
}
Final thoughts
The new "QUERY" method fills a gap that has existed in HTTP for decades. It combines the best parts of "GET" and "POST": the safety and semantics of a read operation with the flexibility of sending a request body.
Whether it becomes widely adopted depends on support from browsers, servers, proxies, API gateways, and frameworks. However, it provides a standardized solution to a problem that many API designers have been solving with "POST" for years.
As HTTP continues to evolve, "QUERY" is a small but meaningful addition that makes API design more expressive and semantically correct.
References
- RFC 10008 — The HTTP QUERY Method
- IETF HTTP Working Group specification
Top comments (3)
This is actually pretty interesting. 😄 My only question is how quickly API gateways, proxies, and frameworks will support QUERY. The spec makes sense, but ecosystem support usually decides whether these things take off. What's your take?
I think frameworks will adopt it fairly quickly, but infrastructure, browsers, and cloud providers usually take longer. I'd watch what Spring, ASP.NET Core, Node.js, API gateways, and the major cloud providers do next.
If support comes quickly across the ecosystem, adoption could be much faster than previous HTTP features. If not, many teams will stay with POST for complex searches simply because it already works. Time will tell. 😊
Hi Iryna, thanks for your advice. I actually have an opportunity that might be a good fit for you. I'm currently working as a Technical Recruiter at Vynt, and we're looking for engineers with strong coding skills and solid English communication skills.
If you're interested in learning more about the role, just let me know. I'd be happy to share the details. Looking forward to hearing from you. Thanks