HTTP QUERY: The New HTTP Method for Complex Body-Based Queries

We've had the same HTTP methods in our everyday development toolbox for years:

GET
POST
PUT
PATCH
DELETE

But HTTP has now gained another method worth knowing:

QUERY

RFC 10008, published in June 2026, defines the QUERY method as a safe and idempotent way to send a query to a server using request content rather than putting the entire query into the URI.

And it addresses a problem many developers have already encountered.

The problem with complex GET queries

For a simple request, GET is perfect:

GET /products?category=phone&brand=apple&page=2

The query is visible, shareable and easy to understand.

But real applications can have much more complicated filtering requirements.

Imagine an analytics dashboard with:

• multiple filters

• nested conditions

• arrays of values

• date ranges

• sorting

• pagination

• range operators

• AND/OR conditions

• large lists of IDs

Trying to represent all of that inside a URI can become unpleasant very quickly.

For example:

GET /products?
category=phone&
brands=apple,samsung,google&
priceMin=10000&
priceMax=150000&
ratingMin=4&
locations=chennai,salem,coimbatore&
sort=price_desc&
page=3&
limit=50

And that's still a relatively simple example.

The HTTP specification notes that URI size limits can become problematic because a request may pass through multiple systems with different constraints.

So what do developers usually do?

A common solution is:

POST /products/search

with the query in the request body:

{
  "filters": {
    "category": ["phone", "laptop"],
    "brands": ["Apple", "Samsung"],
    "price": {
      "min": 10000,
      "max": 150000
    },
    "rating": {
      "min": 4
    }
  },
  "sort": [
    {
      "field": "price",
      "order": "desc"
    }
  ],
  "pagination": {
    "page": 3,
    "limit": 50
  }
}

This works.

But there is a semantic problem.

We're using POST, even though we're not necessarily creating or modifying anything.

We're simply asking:

"Give me the data that matches this query."

The reason POST gets used is largely practical: it provides request content.

Enter QUERY

The new method gives us a dedicated HTTP semantic for this:

QUERY /products
Content-Type: application/json

{
  "filters": {
    "category": ["phone", "laptop"],
    "brands": ["Apple", "Samsung"]
  },
  "sort": [
    {
      "field": "price",
      "order": "desc"
    }
  ],
  "page": 3,
  "limit": 50
}

The query is now in the request content instead of being encoded into the URI.

GET vs QUERY

A useful mental model is:

GET

Client
  │
  │  query parameters
  ▼
/products?category=phone&page=2
  │
  ▼
Server

Whereas:

QUERY

Client
  │
  │  request content
  ▼
/products

{
  "category": ["phone"],
  "page": 2
}
  │
  ▼
Server

The two methods are not identical, though.

QUERY is a distinct HTTP method with its own semantics.

The RFC defines QUERY as safe and idempotent.

That means a QUERY request is intended to retrieve/process information without requesting a change to the target resource, and repeating the request should not introduce additional state changes.

So is QUERY a replacement for GET?

No.

For ordinary requests, GET remains the obvious choice:

GET /users?page=2&limit=20

There is no reason to turn a simple query into:

QUERY /users

with a body containing two fields.

The RFC itself notes that if a query is short enough to fit comfortably in a URI, GET is likely preferable.

QUERY becomes interesting when the query itself becomes large, structured or difficult to express efficiently as URI parameters.

Is QUERY a replacement for POST?

Not exactly.

It's better to think of QUERY as filling a gap between GET and POST.

                 HTTP queries

             ┌───────────────┐
             │               │
             ▼               ▼
           GET             QUERY
             │               │
       query in URI     query in body
             │               │
             └───────┬───────┘
                     │
                  read/query

POST remains useful for creating resources and for operations whose semantics are not safe/idempotent queries.

The interesting part is that developers no longer have to use POST solely because their read query became too complex for the URL.

A practical API example

Suppose we're building a product dashboard.

Simple filtering

GET /products?category=phone&page=2

Use GET.

Advanced filtering

QUERY /products
Content-Type: application/json

{
  "filters": {
    "category": ["phone", "tablet"],
    "brands": ["Apple", "Samsung"],
    "price": {
      "min": 30000,
      "max": 150000
    }
  },
  "sort": [
    {
      "field": "price",
      "order": "desc"
    }
  ],
  "pagination": {
    "page": 2,
    "limit": 50
  }
}

QUERY starts making more sense.

Creating a product

POST /products
Content-Type: application/json

{
  "name": "Example Phone",
  "price": 79999
}

POST.

Updating a product

PATCH /products/123

{
  "price": 74999
}

PATCH.

The methods are expressing different intentions instead of forcing everything through POST.

Another interesting detail

QUERY isn't restricted to JSON.

The RFC defines the request content and its media type as the thing that defines the query.

For example:

QUERY /contacts
Content-Type: application/x-www-form-urlencoded

select=surname,givenname,email&limit=10

The server determines what query formats it supports.

This is an important distinction: QUERY is an HTTP method, not a specific JSON API format.

What about URL length?

One reason this is useful is that URI size limits can be difficult to predict.

A request might pass through:

Browser
   ↓
CDN
   ↓
Proxy
   ↓
Load balancer
   ↓
Web server
   ↓
Application

Different components can have different practical limits.

The RFC notes that HTTP implementations are recommended to support at least 8000 octets, but larger queries can still run into intermediary limitations.

Moving the query into request content avoids encoding a large query entirely into the URI.

Should we start using QUERY everywhere?

No.

The existence of a new HTTP method doesn't mean every GET should become QUERY.

A reasonable mental model is:

Simple read
    ↓
GET

Complex/body-based read
    ↓
QUERY

Create/general operation
    ↓
POST

Replace
    ↓
PUT

Partial update
    ↓
PATCH

Delete
    ↓
DELETE

And there's another practical consideration: the ecosystem needs to support the method.

Your server framework, reverse proxy, API gateway, CDN, client libraries and other infrastructure all need to handle QUERY correctly.

So for an existing production application, blindly replacing working POST search endpoints isn't necessarily a good idea.

But for new API designs, it's a method worth knowing.

The bigger idea

What makes QUERY interesting isn't simply that we now have another HTTP verb.

It's that HTTP now has a clearer way to express something developers have been doing for years:

"I need to send a complex query to the server, but I'm not changing anything."

Previously, many APIs solved that with:

POST /search

Now HTTP has a standardized method that explicitly communicates the intent:

QUERY /search

That's a small addition to the HTTP vocabulary, but potentially a useful one for search APIs, analytics systems, reporting dashboards and other applications with complex query structures.

GET isn't going away. POST isn't going away.

We simply have another tool.

References

• RFC 10008 — The HTTP QUERY Method

• IETF HTTP Semantics