For decades, developers have relied on GET and POST for almost every HTTP request. While these methods work well for most use cases, they have never been ideal for complex search and filtering operations.

The new HTTP QUERY method, standardized in RFC 10008, solves this long-standing problem by introducing a dedicated method for safe, idempotent, read-only requests that can include a request body.

In this article, we'll explore why QUERY was introduced, how it compares with GET and POST, and when you should use each.

---

Why Was a New HTTP Method Needed?

Modern applications rarely perform simple searches.

Think about an e-commerce website where users can filter products by:

• Category
• Multiple brands
• Price range
• Ratings
• Stock availability
• Delivery options
• Nested filters
• Sorting options

These filters can become quite complex.

Until now, developers had two options:

1. Use GET with query parameters.
2. Use POST with a JSON request body.

Neither solution was perfect.

---

GET: Great for Simple Retrieval

GET is the standard HTTP method for retrieving resources.

http
Copy
GET /products?category=laptop&brand=Apple&page=1&sort=price

Advantages

• Safe
• Idempotent
• Cache-friendly
• Bookmarkable
• Supported by every HTTP client

GET is the best choice whenever the request is simple.

Limitations

As filters become more complex, URLs become difficult to maintain.

text
Copy
GET /products?brand=Apple&brand=Dell&priceMin=1000&priceMax=3000&rating=4&availability=in-stock

Now imagine representing nested objects.

json
Copy
{
  "price": {
    "min": 1000,
    "max": 3000
  },
  "location": {
    "lat": 22.3,
    "lng": 70.7,
    "radius": 25
  }
}

Encoding this structure into query parameters quickly becomes messy.

Additionally, URLs have practical length limitations imposed by browsers, proxies, and servers.

---

POST: The Common Workaround

To overcome URL limitations, many APIs use POST.

http
Copy
POST /products/search
Content-Type: application/json

{
  "category": "Laptop",
  "brands": ["Apple", "Dell"],
  "price": {
    "min": 1000,
    "max": 3000
  },
  "sort": "-price"
}

Using a JSON request body makes complex filters much easier to represent.

However, there's one problem.

According to HTTP semantics, POST is intended for operations that process requests or modify server state.

Searching doesn't create, update, or delete anything.

Developers have simply been using POST because GET wasn't expressive enough.

---

Introducing HTTP QUERY

The new QUERY method combines the advantages of GET and POST.

http
Copy
QUERY /products
Content-Type: application/json

{
  "category": "Laptop",
  "brands": ["Apple", "Dell"],
  "price": {
    "min": 1000,
    "max": 3000
  },
  "rating": 4,
  "sort": "-price"
}

The request clearly communicates:

• Retrieve data
• Do not modify server state
• Accept complex structured request bodies

This is exactly what developers have wanted for years.

---

GET vs POST vs QUERY

Note: Caching support for QUERY depends on server, client, and intermediary implementations.

---

Real-World Example

Imagine building a property search API.

GET

http
Copy
GET /properties?city=London&type=Apartment&priceMin=100000&priceMax=500000

Works well for simple searches.

---

POST

http
Copy
POST /properties/search

{
  "city": "London",
  "types": ["Apartment", "Villa"],
  "price": {
    "min": 100000,
    "max": 500000
  }
}

Allows complex filters but isn't semantically correct.

---

QUERY

http
Copy
QUERY /properties

{
  "city": "London",
  "types": ["Apartment", "Villa"],
  "price": {
    "min": 100000,
    "max": 500000
  }
}

Provides the same flexibility while accurately expressing that the operation is read-only.

---

Common Use Cases

The QUERY method is ideal for APIs involving:

• 🔍 Product search
• 🏠 Real estate filtering
• ✈️ Flight and hotel search
• 📊 Analytics dashboards
• 📈 Business intelligence
• 🤖 AI-powered semantic search
• 📚 Elasticsearch/OpenSearch
• 🌍 Geospatial queries
• 📋 Reporting APIs

Any endpoint that performs complex read-only queries can benefit.

---

Should You Use QUERY Today?

Not immediately.

Although RFC 10008 has standardized the method, ecosystem support is still evolving.

Frameworks, browsers, proxies, API gateways, and developer tools are gradually adding support.

For now, many production APIs will continue using POST /search for compatibility.

Over time, QUERY is expected to become the preferred choice for complex search operations.

---

When Should You Use Each Method?

Use GET when:

• Retrieving resources
• Query parameters are simple
• URLs should be shareable or bookmarkable
• Maximum caching is desired

---

Use POST when:

• Creating resources
• Uploading files
• Executing commands
• Performing operations that modify server state

---

Use QUERY when:

• Reading data
• Sending complex JSON filters
• Keeping proper HTTP semantics
• Designing modern search APIs

---

Final Thoughts

The introduction of QUERY doesn't replace GET or POST.

Instead, it fills a gap that has existed since the early days of HTTP.

• GET remains the best choice for simple retrieval.
• POST continues to power create and update operations.
• QUERY finally provides a standardized way to perform complex, read-only searches with structured request bodies.

It's a small addition to the HTTP specification, but one that makes modern API design cleaner, more expressive, and semantically correct.

As support grows across frameworks and infrastructure, don't be surprised if QUERY becomes the new standard for search and filtering endpoints.

---

References

• RFC 10008 — https://www.rfc-editor.org/info/rfc10008
• IETF Datatracker — https://datatracker.ietf.org/doc/rfc10008/