HTTP QUERY: The New HTTP Method That Makes Complex Searches Cleaner

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. 🚀