Introduction
For years, developers have relied on GET and POST for search operations. While GET is the standard choice for retrieving data, it starts to show its limitations when search filters become complex. On the other hand, POST offers flexibility by allowing data in the request body, but it isn't semantically designed for search operations.
Now, a new HTTP method called QUERY aims to bridge that gap by combining the strengths of both GET and POST.
The Problem with GET
The GET method is perfect for simple searches.
Example:
GET /orders?status=paid&sort=created_at
However, as applications grow, search filters become much more sophisticated.
GET /orders?
status=paid&
minTotal=1000&
maxTotal=5000&
customer=John&
country=India&
sort=created_at&
page=2&
includeArchived=true
This quickly results in:
- Long and difficult-to-read URLs
- Browser and server URL length limitations
- Hard-to-maintain API requests
- Exposed query parameters in URLs
For complex filtering, GET becomes increasingly inconvenient.
Why Developers Often Use POST
To avoid lengthy URLs, many developers use POST for search endpoints.
Example:
POST /orders/search
Content-Type: application/json
{
"status": "paid",
"minTotal": 1000,
"maxTotal": 5000,
"sort": "created_at"
}
This approach offers several advantages:
- Clean request payloads
- Easier handling of nested filters
- Better readability
- No URL length concerns
However, POST wasn't originally intended for safe, read-only search operations.
Introducing HTTP QUERY
The new QUERY method is designed specifically for retrieval operations that require a request body.
Example:
QUERY /orders
Content-Type: application/json
{
"status": "paid",
"minTotal": 1000,
"maxTotal": 5000,
"sort": "created_at"
}
It combines the benefits of both traditional methods:
- Supports a request body like POST
- Represents a read-only operation like GET
- Can be treated as safe
- Can be cacheable by HTTP infrastructure
- Better expresses developer intent
GET vs POST vs QUERY
| Feature | GET | POST | QUERY |
|---|---|---|---|
| Request Body | ❌ | ✅ | ✅ |
| Safe (Read-only) | ✅ | ❌ | ✅ |
| Cacheable | ✅ | Limited | ✅ |
| Best for Complex Filters | ❌ | ✅ | ✅ |
| Semantic for Search | ✅ (Simple) | Not Ideal | ✅ |
Why QUERY Matters
Modern applications frequently perform advanced searches involving:
- Multiple filters
- Sorting
- Pagination
- Nested objects
- Date ranges
- Complex search criteria
Developers have traditionally chosen between:
- GET with unwieldy URLs, or
- POST, despite its semantics not aligning with read-only searches.
The QUERY method offers a cleaner, more expressive alternative by allowing complex search criteria in the request body while preserving the semantics of a safe retrieval operation.
Current Adoption
HTTP QUERY is still in the early stages of adoption. While the specification has generated interest within the developer community, support across browsers, servers, frameworks, and API gateways is still evolving.
Widespread adoption will depend on ecosystem support, including web frameworks, proxies, caching layers, and client libraries.
Final Thoughts
The introduction of HTTP QUERY addresses a long-standing challenge in API design. It provides developers with a method that combines the flexibility of POST with the safety and cacheability of GET, making it well-suited for complex search operations.
Although it may take time before QUERY becomes a common feature across the web ecosystem, it represents an important step toward more expressive and maintainable HTTP APIs.
As support grows, QUERY has the potential to become the preferred method for advanced search endpoints, reducing the need to overload POST for read-only operations.
Key Takeaways
- GET is ideal for simple searches but struggles with complex filters.
- POST supports request bodies but isn't intended for read-only retrieval.
- QUERY introduces body-based search while remaining safe and cacheable.
- It improves API readability, maintainability, and semantic correctness.
- Broader ecosystem support will determine how quickly it becomes a mainstream HTTP method.
The future of search APIs might just be QUERY. 🚀
.png)
Follow Us
Were this world an endless plain, and by sailing eastward we could for ever reach new distances