HTTP Just Got a New Method: Why QUERY Changes API Design

Karan — Thu, 16 Jul 2026 10:50:13 +0000

One of API design's most familiar workarounds may finally have an expiration date.

For years, API designers have quietly made the same compromise.

They start with a clean GET request:

GET /products?category=laptop&brand=acme HTTP/1.1
Host: api.example.com
Accept: application/json

Then the product team asks for price ranges, multiple brands, availability rules, nested attributes, full-text search, sorting, pagination, and user-specific constraints.

The URL begins to look less like an address and more like a programming language:

/products
└── filters
    ├── category = laptop
    ├── brands = [acme, contoso, globex]
    ├── price
    │   ├── minimum = 800
    │   └── maximum = 1800
    ├── specifications
    │   ├── memory >= 32 GB
    │   └── storage = SSD
    └── sort = rating desc, price asc

So the team moves the filters into JSON and sends them with POST:

POST /products/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "brands": ["acme", "contoso", "globex"],
  "price": { "min": 800, "max": 1800 },
  "specifications": {
    "memoryGb": { "gte": 32 },
    "storageType": "ssd"
  },
  "sort": ["-rating", "price"]
}

The endpoint works. The JSON is readable. The server returns products. But the method is now vague: without endpoint-specific knowledge, POST could mean a safe search, a payment, a message submission, or some other state-changing command.

In June 2026, RFC 10008 gave that operation its own method:

QUERY /products HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "brands": ["acme", "contoso", "globex"],
  "price": { "min": 800, "max": 1800 },
  "sort": ["-rating", "price"]
}

QUERY gives complex reads request content without giving up explicit read-only, retry, and caching semantics.

HTTP Methods Are Tiny Words With Large Contracts

GET, POST, PUT, and DELETE are method tokens with standardized meanings. Those meanings let clients, servers, caches, proxies, gateways, and monitoring systems reason about a request before they understand the application behind it.

The method is the first line of the contract:

HTTP request
├── method: What kind of operation is this?
├── target: Which resource is in scope?
├── fields: What metadata applies?
└── content: What representation accompanies the request?

Three properties matter to the QUERY story:

Property	What it actually means	What it does not mean
Safe	The client does not request a change to the target resource's state	The server performs no work, writes no logs, or creates no auxiliary resources
Idempotent	Repeating the same request has the same intended effect as sending it once	Every response must contain identical data
Cacheable	A response may be stored and reused under HTTP caching rules	Every CDN will cache it automatically

Idempotent does not mean identical responses. GET /products/42 can return \$900 today and \$850 tomorrow; GET remains idempotent because repeated reads request no additional state change. PUT and DELETE are also idempotent despite changing state. POST is not idempotent by definition because replaying it may repeat an action. PATCH may be idempotent in a specific use, but HTTP does not guarantee it.

The Gap Between GET and POST

GET is an excellent fit when query input fits naturally in the target URI:

GET /feed?q=http&limit=10&sort=-published HTTP/1.1
Host: example.org

It clearly communicates a safe, idempotent retrieval. Its responses work naturally with browsers, shared caches, CDNs, bookmarks, links, and observability tools.

Complex queries expose four practical limits:

Clients, proxies, gateways, and servers impose different limits on request targets. **RFC 9110* recommends support for at least 8,000 octets, but your path is only as tolerant as its most restrictive hop.*
Nested filters, arrays, ranges, and query languages become awkward once they are flattened via encoding into a query string.
Request URIs often appear in logs, browser history, bookmarks, referrers, and monitoring tools. Request content can also be logged, but it is less widely exposed by default.
With GET, every input combination becomes a distinct URI. That is useful for small filters and clumsy for large query documents.

POST avoids those limits because it expects request content. It also loses the generic signal that the operation is a safe, idempotent query.

That is the gap QUERY fills.

What QUERY Actually Means

RFC 10008 defines QUERY as a method that asks the target resource to perform a server-side query within that resource's scope. The request's content and Content-Type define the query. The target URI defines the resource being queried.

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/jsonpath
Accept: application/json

$[?(@.country == "India" && @.status == "active")]

Here, /contacts establishes the scope. application/jsonpath tells the server how to interpret the content. The JSONPath expression describes the query.

A server must reject a QUERY request when Content-Type is missing or inconsistent with the content. That requirement is not decorative. The same bytes could have completely different meanings under application/json, application/sql, or application/jsonpath.

QUERY is not simply “GET with a body”

That phrase is a useful first approximation, but it hides the semantic difference.

GET asks for a current representation of the resource identified by the target URI.
QUERY asks the target resource to perform the operation described by the request content.

HTTP assigns no generally defined semantics to content in a GET request. Some implementations reject it, some ignore it, and intermediaries cannot safely assume what it means.

Capability	GET	QUERY	POST
Safe by definition	Yes	Yes	No
Idempotent by definition	Yes	Yes	No
Request content	No generally defined semantics	Expected	Expected
Query identified entirely by URI	Yes	No	No
Response can satisfy the same method later	Yes	Yes	No
Best fit	Ordinary retrieval and compact filters	Complex, read-only queries	Submissions and application-defined processing

POST responses can be cached under specific conditions, but a stored response generally cannot satisfy a later POST. By design, a cached QUERY response can satisfy an equivalent later QUERY.

The Most Important Part: Caching the Content

A cache normally starts with the method and target URI when matching requests. That is insufficient for QUERY.

These two requests target the same URI but ask different questions:

QUERY /products HTTP/1.1
Content-Type: application/json

{"brand":"acme"}

QUERY /products HTTP/1.1
Content-Type: application/json

{"brand":"globex"}

If a cache considered only /products, it could return Acme results to a client asking for Globex. RFC 10008 therefore requires a QUERY cache key to incorporate the request content and related metadata.

A cache may normalize semantically insignificant differences before generating the key. For example, these JSON documents might mean the same thing:

{"brand":"acme","inStock":true}

{
  "inStock": true,
  "brand": "acme"
}

But normalization is dangerous when the cache and application disagree about meaning. A false match can return the wrong data. The safest initial implementation is often a deterministic query format plus a hash of the exact content and relevant metadata.

This is why “QUERY is cacheable” does not mean “every CDN supports it today.” A compliant QUERY cache must read the full request content and include it in matching.

A Query Can Become a GET-able Resource

RFC 10008 offers another useful pattern. A server can assign a URI to the query itself, to the result that was just produced, or to both.

HTTP/1.1 200 OK
Content-Type: application/json
Location: /products/stored-queries/42
Content-Location: /products/stored-results/17
ETag: "result-17"

[
  { "id": 7, "brand": "acme", "price": 1299 },
  { "id": 9, "brand": "contoso", "price": 1499 }
]

The two response fields serve different purposes:

Field	Identifies	A later GET means
`Location`	An equivalent resource representing the query and its target	Retrieve the current result equivalent to executing that query
`Content-Location`	A resource corresponding to the result just returned	Retrieve that result representation

The distinction matters when the underlying data changes. A stored query can produce a newer answer. A stored result can represent the answer from a particular execution.

QUERY also supports conditional requests. Once a client has an ETag or Last-Modified validator, it can ask for results only if they changed. If the server supplies a Location for an equivalent resource, subsequent GET requests can make that flow simpler and more widely compatible.

Safe Retries Are a System Design Feature

Imagine a client sends a complex search and the connection drops before the response arrives.

With an application-specific POST endpoint, the client cannot infer from the method alone whether retrying might repeat a state change. It needs out-of-band knowledge of that endpoint's behavior.

QUERY carries the answer in the protocol. It is idempotent, so clients and intermediaries can repeat it after a connection failure without introducing a second requested state change.

Connection fails
├── POST
│   └── Retry only with endpoint-specific knowledge or safeguards
└── QUERY
    └── Retry is allowed by the method's idempotent semantics

Servers Can Advertise QUERY Support

The RFC also defines the Accept-Query response field. A resource can use it to advertise the media types it accepts as query content:

HEAD /products HTTP/1.1
Host: api.example.com

HTTP/1.1 200 OK
Accept-Query: application/json, application/jsonpath

This tells the client that the resource supports QUERY with JSON or JSONPath content. Content-Type identifies the query format, while Accept lists the desired response formats.

Request format                         Response format
Content-Type: application/json         Accept: application/json
             │                                  │
             └── how to read the query          └── how to return the result

Why You Should Not Replace Every GET Tomorrow

QUERY is now standardized. Standardization and universal deployment are not the same event.

An HTTP request usually crosses a chain of components:

Client
  └── SDK or browser
      └── corporate proxy
          └── CDN or edge cache
              └── WAF
                  └── API gateway
                      └── application server
                          └── route handler

Every component must either understand QUERY or pass it through correctly. Before adopting it, verify the boring path:

The client can send an extension method with content.
Proxies, firewalls, and gateways do not reject or rewrite it.
The application server can route it.
Cache behavior includes content and relevant metadata in the key.
Authentication and authorization are evaluated before query execution.
Logs and tracing systems label it correctly without exposing sensitive content.
Rate limits account for query cost, not merely request count.
Cross-origin browser calls complete the required CORS preflight.

There is also a security misconception worth removing:

Request content is less likely than a URI to appear in routine logs. It is not automatically private.

Use HTTPS. Redact sensitive fields. Validate the query language. Apply authorization at the data level. Limit depth, joins, result size, and execution time. A beautifully semantic method can still carry an expensive or malicious query.

The Bigger Lesson Is Not About One New Word

HTTP methods help distributed systems communicate intent. GET says, “Give me a representation of this resource.” POST says, “Process this content according to this resource's rules.” QUERY now says, “Safely process this query and give me the result.”

Simple filters should remain GET requests. Existing POST search endpoints will not suddenly stop working. But when a read operation becomes too expressive for a URI and your request path supports it, developers no longer have to choose between readable content and honest HTTP semantics.

The gap finally has a method.

The one sentence to remember: QUERY is a safe, idempotent, content-bearing HTTP method for complex server-side queries.

DEV Community: Karan