HTTP QUERY: The New HTTP Method That Bridges GET and POST

For decades, developers have primarily relied on HTTP methods such as GET, POST, PUT, PATCH, and DELETE to build APIs. Each method serves a specific purpose: GET retrieves data, POST creates it, PUT and PATCH update it, and DELETE removes it. These methods have served the web well, but API developers often faced a common challenge: how to perform complex read-only queries without overloading URLs or misusing POST requests.

When Simple GET Requests Aren’t Enough

The problem became especially clear when queries grew complicated. GET requests must stay safe and idempotent, but they only let you pass parameters through the URL. This works fine for simple searches, but breaks down when you need to filter by multiple fields, apply nested conditions, or send large amounts of structured data. URLs carry practical length limits, and cramming complex logic into query strings quickly becomes messy and hard to maintain.

The POST Workaround — and Its Hidden Cost

To work around this, many developers turned to POST requests instead, even for operations that were purely read-only. This let them send complex filters and parameters in the request body, but it came at a cost: POST exists to create or modify data, not read it. Using it for queries broke the semantic meaning of HTTP methods, confused caching systems that assume POST requests aren’t safe to cache, and made APIs harder to reason about for both developers and tools.

This is where the newly proposed HTTP QUERY method comes in. It fills this gap by allowing a safe, idempotent, read-only request that can still carry a request body, just like POST. In other words, it gives developers the best of both worlds: the semantic clarity of a “read” operation, combined with the flexibility of sending complex query parameters in the body rather than the URL.

The Problem with GET and POST

Traditionally, retrieving data is done using GET:

GET /users?role=admin&status=active&sort=name

This works well for simple filters. However, modern applications often require:

• Deeply nested filters
• Complex search criteria
• Large JSON payloads
• GraphQL-style queries
• Advanced analytics requests

Encoding such information in a URL can become cumbersome and may run into URI length limitations. Additionally, query parameters are often logged and exposed in browser history.

As a workaround, developers frequently use POST:

POST /users/search
Content-Type: application/json

{
  "role": "admin",
  "status": "active",
  "department": ["Engineering", "Security"]
}

Although functional, POST is generally associated with operations that may modify server state. This creates semantic ambiguity for read-only operations.

Enter HTTP QUERY

The QUERY method is designed specifically for read-only operations that require a request body.

Example:

QUERY /users
Content-Type: application/json

{
  "role": "admin",
  "status": "active",
  "department": ["Engineering", "Security"]
}

The server processes the query and returns matching results without changing application state.

Key Characteristics of QUERY

1. Safe

Like GET, QUERY is considered a safe method.

A QUERY request should not create, update, or delete resources. It is intended purely for data retrieval.

2. Idempotent

Sending the same QUERY request multiple times should produce the same result and should not cause side effects

3. Supports Request Bodies

Unlike GET, QUERY is specifically designed to carry request content in the body. This makes it ideal for complex searches and filtering operations.

4. Better API Semantics

QUERY clearly communicates developer intent:

• GET → Simple retrieval
• QUERY → Complex retrieval
• POST → Resource creation or processing

This makes APIs more expressive and easier to understand.

QUERY vs GET vs POST

Conclusion

In conclusion, the HTTP QUERY method offers a modern solution for complex read-only operations by combining the safety and idempotency of GET with the flexibility of request bodies. Furthermore, it helps developers create cleaner and more expressive APIs for advanced search, analytics, and reporting use cases. Although adoption may take time, QUERY has the potential to bridge the gap between GET and POST and become an important part of the future API landscape.