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)

---

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:

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:

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)

---

Enter HTTP QUERY

The new HTTP method is simply:

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:

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.

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)

---

3. Supports Request Body

This is the biggest feature.

Unlike GET:

GET /search?q=phone

QUERY supports:

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)

---

Example: Product Search

GET

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

Readable, but increasingly unwieldy as filters grow.

---

POST

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

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:

POST /graphql

{
    "query":"..."
}

Even though GraphQL queries are read-only.

With QUERY:

QUERY /graphql

{
    "query":"..."
}

The HTTP method now matches the operation's semantics. (HTTP.DEV)

---

Analytics APIs

Current approach:

POST /analytics/report

Payload:

{
    "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:

POST /_search

QUERY provides a standardized alternative:

QUERY /_search

---

SQL Queries

Instead of:

POST /database/query

You could use:

QUERY /database

Body:

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)

For expensive queries:

QUERY /analytics

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

---

Automatic Retries

If a network interruption occurs:

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:

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

Or:

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

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

---

Typical Response

HTTP/1.1 200 OK

Content-Type: application/json

{
    "items":[]
}

Or:

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)

---

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)

---

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.