For years, developers have relied on GET and POST to build search and filtering APIs. While both methods work, neither was designed specifically for complex read-only queries.
The newly standardized HTTP QUERY method (RFC 10008) fills this long-standing gap by introducing a method for safe, idempotent, read-only requests that can include a request body.
Let's break down why this matters.
The Problem with GET
GET is the standard HTTP method for retrieving resources.
GET /products?category=laptop&brand=Apple&page=1&sort=price
Advantages
✅ Safe
✅ Idempotent
✅ Cache-friendly
✅ Bookmarkable
✅ Supported by every HTTP client
Limitations
As search requirements become more advanced, URLs quickly become difficult to manage.
Imagine filtering products by:
Multiple brands
Price range
Categories
Ratings
Availability
Nested filter groups
The URL can become long and difficult to maintain.
GET /products?brand=Apple&brand=Dell&priceMin=1000&priceMax=3000&rating=4&availability=in-stock...
Nested objects and arrays are especially awkward to represent in query parameters.
The POST Workaround
To avoid URL limitations, many APIs use POST for searching.
POST /products/search
Content-Type: application/json
{
"category": "Laptop",
"brands": ["Apple", "Dell"],
"price": {
"min": 1000,
"max": 3000
},
"sort": "-price"
}
This solves the payload problem but introduces another one.
POST is intended for operations that process requests or change server state.
Searching for products doesn't create, update, or delete anything.
Developers have been using POST simply because GET couldn't carry complex request bodies.
Introducing HTTP QUERY
The QUERY method combines the advantages of both GET and POST.
QUERY /products
Content-Type: application/json
{
"category": "Laptop",
"brands": ["Apple", "Dell"],
"price": {
"min": 1000,
"max": 3000
}
}
It clearly communicates that the operation:
retrieves data
does not modify server state
accepts a structured request body
GET vs POST vs QUERY
Instead of a table, here's a clear breakdown:
GET
- Read-only: ✅
- Request Body: ❌
- Safe: ✅
- Idempotent: ✅
- Complex JSON Filters: ❌
- URL Length Issues: ✅
- Cache Friendly: ✅
- Best Semantics for Search: ⚠️
POST
- Read-only: ✅
- Request Body: ✅
- Safe: ❌
- Idempotent: ❌
- Complex JSON Filters: ✅
- URL Length Issues: ❌
- Cache Friendly: Limited
- Best Semantics for Search: ❌
QUERY
- Read-only: ✅
- Request Body: ✅
- Safe: ✅
- Idempotent: ✅
- Complex JSON Filters: ✅
- URL Length Issues: ❌
- Cache Friendly: Possible*
- Best Semantics for Search: ✅
Caching support depends on server, client, and intermediary implementations.
Where QUERY Makes Sense
The new method is particularly useful for:
🔍 Product search
🏠 Real estate filtering
✈️ Travel search
📊 Analytics dashboards
🤖 AI-powered search
📚 Elasticsearch/OpenSearch queries
🌍 Geospatial search
📈 Business intelligence reports
Any endpoint that performs complex read-only queries is a good candidate.
Should You Start Using It Today?
Not immediately.
Although QUERY is now part of the HTTP standard, support across browsers, frameworks, proxies, API gateways, and developer tools is still evolving.
For now, many APIs will continue using POST /search for compatibility.
As the ecosystem adopts the new method, QUERY provides a cleaner and more semantically correct option for complex searches.
Final Thoughts
The introduction of QUERY doesn't replace GET or POST.
Instead, it fills a gap that developers have worked around for years.
Use GET for simple resource retrieval.
Use POST for creating or modifying resources.
Use QUERY for complex, read-only operations that require a request body.
It's a small addition to HTTP, but one that can make API design clearer and more expressive.
What do you think?
Would you adopt QUERY for your search endpoints once your framework and infrastructure support it, or will you continue using POST /search for compatibility?
I'd love to hear your thoughts in the comments.
References
RFC 10008 — HTTP QUERY Method
Top comments (0)