Meet HTTP QUERY: The New HTTP Method You've Probably Been Waiting For
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 c
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=..
Enter fullscreen mode Exit fullscreen mode
you can send:
QUERY /products
Content-Type: application/json
{
"category": "laptops",
"brand": "Lenovo",
"price": {
"min": 1000,
"max": 2500
},
"features": [
"32GB RAM",
"OLED"
]
}
Enter fullscreen mode Exit fullscreen mode
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
