# The New HTTP QUERY Method: The Missing Piece Between GET and POST

For decades, API developers have faced a frustrating dilemma:

*   **GET** is the correct HTTP method for retrieving data, but it doesn't officially support a request body and has practical URL length limitations.
    
*   **POST** allows sending complex request bodies but semantically represents an unsafe operation, even when the request is only fetching data.
    

To solve this long-standing problem, the IETF introduced a new HTTP method called `QUERY`. It is designed specifically for **safe, idempotent read operations that require a request body**. Initially proposed as an Internet-Draft, it has since been standardized as **RFC 10008**. ([RFC Editor](https://www.rfc-editor.org/info/rfc10008/?utm_source=voiceofdev.in))

* * *

# Why Was QUERY Needed?

Modern applications rarely perform simple searches.

Today's APIs often require:

*   Complex filtering
    
*   Nested objects
    
*   Arrays of values
    
*   Date ranges
    
*   Geospatial filters
    
*   GraphQL queries
    
*   SQL-like expressions
    
*   Analytics requests
    
*   Full-text search configurations
    

Trying to encode these into a GET URL quickly becomes problematic.

Example:

```http
GET /products?
category=electronics&
priceMin=100&
priceMax=500&
brands=Apple,Sony,Samsung&
rating=4&
sort=price&
availability=true&
warehouse=US&
color=black&
...
```

Eventually:

*   URLs become thousands of characters long.
    
*   Some browsers, proxies, gateways, and servers impose URL length limits.
    
*   Nested JSON structures become impossible to represent cleanly.
    

Many developers therefore switched to POST:

```http
POST /products/search

{
    "category":"electronics",
    "price":{
        "min":100,
        "max":500
    },
    "brands":[
        "Apple",
        "Sony"
    ]
}
```

The problem?

Although the endpoint only retrieves data, POST communicates that the request may modify server state, which limits caching and automatic retries. ([HTTP.DEV](https://http.dev/query?utm_source=voiceofdev.in))

* * *

# Enter HTTP QUERY

The new HTTP method is simply:

```http
QUERY
```

Conceptually it behaves like:

> "GET with a request body."

It allows clients to send structured query data inside the request body while preserving the semantics of a read-only operation.

Example:

```http
QUERY /products

Content-Type: application/json

{
    "category":"electronics",
    "price":{
        "min":100,
        "max":500
    },
    "brands":[
        "Apple",
        "Sony"
    ],
    "sort":"price"
}
```

* * *

# Core Characteristics

## 1\. Safe

QUERY **must not modify server state**.

Like GET:

*   Searching
    
*   Filtering
    
*   Reading
    
*   Aggregating
    
*   Analytics
    

are valid.

Invalid examples:

*   Creating users
    
*   Updating products
    
*   Deleting records
    

* * *

## 2\. Idempotent

Sending the exact same QUERY multiple times should produce the same logical effect.

```plaintext
QUERY
QUERY
QUERY
```

No matter how many times it is repeated:

*   No duplicate records
    
*   No extra inserts
    
*   No unintended updates
    

This makes QUERY safe for retries after transient network failures. ([RFC Editor](https://www.rfc-editor.org/info/rfc10008/?utm_source=voiceofdev.in))

* * *

## 3\. Supports Request Body

This is the biggest feature.

Unlike GET:

```http
GET /search?q=phone
```

QUERY supports:

```http
QUERY /search

{
    "keyword":"phone",
    "filters":{
        "price":{
            "min":100
        }
    }
}
```

The request body can be:

*   JSON
    
*   XML
    
*   SQL
    
*   GraphQL
    
*   Protocol Buffers
    
*   CBOR
    
*   Any media type the server supports
    

* * *

# GET vs POST vs QUERY

| Feature | GET | POST | QUERY |
| --- | --- | --- | --- |
| Retrieves data | ✅ | ✅ | ✅ |
| Request body | Not defined by HTTP semantics | ✅ | ✅ |
| Safe | ✅ | ❌ | ✅ |
| Idempotent | ✅ | ❌ | ✅ |
| Cacheable | ✅ | Limited | ✅ |
| Retry friendly | ✅ | Risky | ✅ |
| Complex payload | ❌ | ✅ | ✅ |

QUERY effectively fills the gap between GET and POST. ([HTTP.DEV](https://http.dev/query?utm_source=voiceofdev.in))

* * *

# Example: Product Search

## GET

```http
GET /products?
category=laptop&
brand=Apple&
ram=16&
storage=512&
priceMin=500&
priceMax=1500
```

Readable, but increasingly unwieldy as filters grow.

* * *

## POST

```http
POST /products/search

{
    "category":"Laptop",
    "brand":"Apple",
    "ram":16,
    "storage":512
}
```

Works technically, but semantically uses a method intended for potentially state-changing operations.

* * *

## QUERY

```http
QUERY /products

{
    "category":"Laptop",
    "brand":"Apple",
    "ram":16,
    "storage":512
}
```

This expresses the intent clearly: a read-only query with structured input.

* * *

# GraphQL Benefits

Many GraphQL servers use POST:

```http
POST /graphql

{
    "query":"..."
}
```

Even though GraphQL queries are read-only.

With QUERY:

```http
QUERY /graphql

{
    "query":"..."
}
```

The HTTP method now matches the operation's semantics. ([HTTP.DEV](https://http.dev/query?utm_source=voiceofdev.in))

* * *

# Analytics APIs

Current approach:

```http
POST /analytics/report
```

Payload:

```json
{
    "startDate":"2026-01-01",
    "endDate":"2026-06-30",
    "dimensions":[
        "country",
        "browser"
    ],
    "metrics":[
        "users",
        "sessions"
    ]
}
```

This is a read-only operation and is a natural fit for QUERY instead.

* * *

# Elasticsearch-Style Searches

Many search engines already use POST for searches:

```plaintext
POST /_search
```

QUERY provides a standardized alternative:

```plaintext
QUERY /_search
```

* * *

# SQL Queries

Instead of:

```http
POST /database/query
```

You could use:

```http
QUERY /database
```

Body:

```sql
SELECT *
FROM users
WHERE country='India'
```

This clearly indicates a read-only query.

* * *

# Caching

One of the biggest advantages is that QUERY responses can be cached, provided the implementation accounts for the request body as part of the cache key. ([Kreya](https://kreya.app/blog/new-http-query-method-explained/?utm_source=voiceofdev.in))

For expensive queries:

```http
QUERY /analytics
```

the first response can be stored and reused for identical requests.

* * *

# Automatic Retries

If a network interruption occurs:

```plaintext
Client
   |
QUERY
   |
Network timeout
```

The client can safely retry because QUERY is idempotent.

Retrying POST is often unsafe because it may create duplicate side effects.

* * *

# Content Negotiation

QUERY works with standard HTTP headers:

```http
Content-Type: application/json
Accept: application/json
```

Or:

```http
Content-Type: application/sql
Accept: text/csv
```

The response format remains flexible, just like with other HTTP methods.

* * *

# Typical Response

```http
HTTP/1.1 200 OK

Content-Type: application/json

{
    "items":[]
}
```

Or:

```http
HTTP/1.1 303 See Other

Location: /queries/12345
```

Servers may also expose a stable URI for a stored query result when appropriate. ([RFC Editor](https://www.rfc-editor.org/info/rfc10008/?utm_source=voiceofdev.in))

* * *

# Practical Use Cases

QUERY is especially well-suited for:

*   Advanced search APIs
    
*   Product filtering
    
*   E-commerce catalogs
    
*   BI dashboards
    
*   Reporting systems
    
*   Analytics platforms
    
*   GraphQL query execution
    
*   Search engines
    
*   SQL-over-HTTP
    
*   AI retrieval APIs
    
*   Log exploration
    
*   Time-series data queries
    
*   Elasticsearch/OpenSearch-style endpoints
    
*   Vector search and semantic search
    

* * *

# Adoption Status

The QUERY method is now defined in **RFC 10008**, but ecosystem support is still emerging. Many HTTP clients, frameworks, proxies, API gateways, and cloud platforms have mature support for GET and POST, while QUERY may require updates before it works end-to-end everywhere. In practice, many public APIs will continue using POST for complex read operations until tooling catches up. ([RFC Editor](https://www.rfc-editor.org/info/rfc10008/?utm_source=voiceofdev.in))

* * *

# Should You Use QUERY Today?

If you control both the client and server and your infrastructure supports custom HTTP methods, QUERY provides a cleaner, standards-based way to model complex read-only operations.

For public APIs intended to work with the broadest range of existing clients, proxies, and gateways, POST remains the most interoperable choice for now, despite its semantic drawbacks.

As support for RFC 10008 expands across web frameworks and infrastructure, QUERY has the potential to become the preferred method for complex, read-only API requests that need a request body.