The HTTP QUERY Method

1. Overview / TL;DR

QUERY is a new HTTP request method, standardized in RFC 10008 (published June 2026 by J. Reschke, J.M. Snell, and M. Bishop under the IETF HTTPBIS working group). It sits deliberately between GET and POST: like POST, it carries a request body; like GET, it is explicitly safe and idempotent, so it can be cached, retried, and prefetched automatically.

This page is a from-source deep dive: it pulls directly from the RFC text and the working-group drafts that preceded it, plus the practical ecosystem status as of mid-2026 (which frameworks and servers actually support it, and what still needs manual wiring).

2. Why It Was Needed

Every API that supports rich filtering, search, or reporting eventually runs into the same fork: encode the query in the URI (GET), or smuggle it into a request body (POST). RFC 10008 spells out why both are unsatisfying.

The problem with GET + URI query parameters

• Unpredictable size limits — a request can pass through many uncoordinated intermediaries (proxies, load balancers, CDNs, WAFs), each with its own undocumented URI length cap. There is no reliable way to know in advance whether a complex query will fit.
• Inefficient encoding — structured or nested data (arrays of objects, boolean expressions, full-text search syntax) is awkward and verbose once flattened into application/x-www-form-urlencoded key/value pairs.
• Privacy / logging exposure — request URIs are logged far more readily than request content by proxies, servers, browser history, and analytics tools, and they show up in bookmarks. A URI-encoded query leaks more than the equivalent content in a body.
• Resource identity blow-up — under strict HTTP semantics, every distinct query string is technically a distinct resource identifier, which sits awkwardly with how people actually think about "the same search, different parameters."

The problem with POST

POST has no fixed safety or idempotency contract — RFC 9110 explicitly leaves both open. That means:

• A client (or an intermediary, or a cache) cannot tell, just from the method, whether a given POST is a harmless read or a state-changing write.
• Automatic retries are unsafe by default — if a connection drops mid-request, blindly resending a POST risks double-processing a mutation.
• Caches generally treat POST responses as non-cacheable or only cacheable under narrow, explicit conditions.

Earlier attempts to close this gap — SEARCH, REPORT, PROPFIND — all originate from the WebDAV activity and tie their semantics to a generic application/xml body, with "mixed feelings" (the RFC's own words) about reusing WebDAV machinery for general-purpose APIs. QUERY was designed as a clean, media-type-agnostic alternative whose name directly captures its relationship to the URI's query component.

3. Syntax & Basic Example

A QUERY request looks exactly like a POST at the wire level, except for the method token and the semantics that come with it. The request content is the query; its media type tells the server how to interpret it.

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

HTTP/1.1 200 OK
Content-Type: application/json

[
  { "surname": "Smith",
    "givenname": "John",
    "email": "smith@example.org" },
  { "surname": "Jones",
    "givenname": "Sally",
    "email": "sally.jones@example.com" }
]

The request URI still matters: it identifies the target resource the query is run against (here, /contacts), the same way a POST target identifies where data is submitted. What's new is that the body's job is unambiguous — it is the query, not "maybe a query, maybe a mutation, depends on the endpoint."

4. Safety & Idempotency

These two properties, inherited from RFC 9110's definitions, are the entire reason QUERY is useful to caches, proxies, and retry logic.

Practically, this unlocks behavior that was never safe to apply to a generic POST:

• HTTP clients and load balancers can automatically retry a failed QUERY the same way they retry a GET, without a "was this already applied?" concern.
• Caches are explicitly permitted to store and reuse QUERY responses (see §7).
• Tooling (linters, API gateways, WAFs) can treat QUERY as read-only traffic for rate-limiting, auditing, and access-control purposes without inspecting the body's business logic.

5. Content-Type & Error Handling

Because the body is the query, the media type is not optional decoration — it is load-bearing. The RFC is blunt about this:

The spec gives explicit guidance on which status code to use for which failure mode:

This is a meaningfully richer error vocabulary than a typical GET-with-query-string endpoint, which usually collapses "malformed query" and "query about something that doesn't exist" into an undifferentiated 400.

6. Accept-Query & Discovery

A client needs a way to find out, ahead of time, whether a resource supports QUERY at all and which query formats it accepts. RFC 10008 defines a new response header for exactly this, Accept-Query, encoded as an HTTP Structured Field (RFC 9651) of type List.

HEAD /contacts HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Accept-Query: "application/x-www-form-urlencoded", "application/sql"

OPTIONS /contacts HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Allow: GET, QUERY, OPTIONS, HEAD

Media types in Accept-Query can carry parameters and wildcards (*/* or type/*), the same as a client's own Accept header. One subtlety worth internalizing: the value of Accept-Query applies to every URI that shares the same path — the query component of the URI itself is ignored for this purpose, since QUERY's own request content is what varies, not the URI.

7. Caching Semantics

Because QUERY is safe, its responses are explicitly cacheable — but the cache key can no longer be just the URI, since the query lives in the body.

Caches are allowed to normalize semantically-insignificant differences before computing that key — stripping content-encoding, or normalizing format conventions such as a +json media-type suffix — but any such transformation exists purely to compute the cache key. It never changes the actual request sent onward. The RFC also flags the obvious risk here: a cache that normalizes incorrectly, or too aggressively, can serve a stale or simply wrong response if two content bodies that aren't really equivalent get folded into the same key (see §9).

8. Content-Location, Location & Equivalent Resource

QUERY introduces the concept of an equivalent resource: a plain GET-able resource that represents a particular QUERY request (its target plus its content) and can be re-fetched with a normal, bodyless GET. Servers aren't required to expose this, but if they do, they signal it with response headers.

Content-Location — "here's a URI for exactly these results"

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/stored-results/17

[ ...results... ]

This is a claim that a client can GET /contacts/stored-results/17 later to retrieve this specific result set again.

Location — "here's a URI that re-runs the same query"

HTTP/1.1 200 OK
Content-Type: application/json
Location: /contacts/stored-queries/42

[ ...results... ]

This is a claim that a plain GET /contacts/stored-queries/42 will repeat the query operation itself — useful for bookmarking a saved search or sharing a link without re-sending the original request body.

9. Redirects & Conditional Requests

Redirect status codes

• 301 / 308 (permanent) and 302 / 307 (temporary) — the server suggests the client repeat the same kind of request (another QUERY, with the same content) against the new Location. Unlike POST, a QUERY does not silently downgrade to GET after one of these.
• 303 See Other — signals that the query's results can be fetched with a plain GET against the URI in Location, without resending the original content.

Conditional requests

The "selected representation" for a QUERY is defined the same way as for an equivalent GET, so standard conditional headers — If-Modified-Since, If-None-Match, etc. — work as expected: a conditional QUERY only returns a body when the condition is met.

Range requests

Byte-range semantics carry over unchanged from GET, but the RFC is candid that they're rarely useful here — query result formats typically define their own pagination (SQL's FETCH FIRST … ROWS ONLY, or a JSON API's limit/offset), and clients are expected to use those instead of HTTP byte ranges.

10. GET vs QUERY vs POST

Why not reuse SEARCH, REPORT, or PROPFIND?

These predate QUERY and can express similar ideas, but the working group rejected reusing them for two reasons stated directly in the spec: they originate from WebDAV, which the wider HTTP community has "mixed feelings" about depending on outside a WebDAV context; and they tie their semantics to a single generic application/xml body, whereas QUERY is media-type-agnostic — the query format is a first-class, negotiable property of the request (see §6), not baked into the method's own spec.

11. Security Considerations

12. Ecosystem & Adoption Status (mid-2026)

RFC 10008 is a finished Proposed Standard, but standardization and ecosystem support are two different clocks. As of mid-2026, here's the honest state of things:

13. Using QUERY in Code

Client: browser fetch()

const res = await fetch('/api/products', {
  method: 'QUERY',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ category: 'shoes', maxPrice: 100, sort: '-rating' })
})
const products = await res.json()

Client: curl

curl -X QUERY https://shop.example.com/products \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'category=shoes&maxPrice=100&sort=-rating'

Client: Node.js (core http module)

import http from 'node:http'

const req = http.request('http://example.org/contacts', {
  method: 'QUERY',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
}, (res) => {
  let data = ''
  res.on('data', chunk => data += chunk)
  res.on('end', () => console.log(JSON.parse(data)))
})
req.end('select=surname,email&limit=10')

Server: Express (manual routing until native support lands)

Express doesn't yet expose app.query(), but the method still arrives on req.method, so it can be dispatched by hand:

app.use('/contacts', (req, res, next) => {
  if (req.method !== 'QUERY') return next()

  if (!req.is('application/x-www-form-urlencoded')) {
    return res.status(415).send('Unsupported query format')
  }

  const { select, limit } = req.body // parsed by a urlencoded body parser
  const results = runContactQuery({ select, limit })

  res.set('Accept-Query', 'application/x-www-form-urlencoded')
  res.json(results)
})

14. When to Use QUERY vs GET vs POST

References

• 1
  RFC 10008 — The HTTP QUERY Method

  The canonical, published Standards Track specification. Source for every normative claim on this page.
• 2
  draft-ietf-httpbis-safe-method-w-body (IETF Datatracker)

  The working-group draft history (versions 02–14) that led to RFC 10008 — useful for seeing how the design evolved.
• 3
  RFC Editor: Info page for RFC 10008

  Publication metadata, status, and errata tracking for the RFC.
• 4
  IETF Announcement: RFC 10008 on The HTTP QUERY Method

  The official ietf-announce mailing list publication notice.
• 5
  RFC 9110 — HTTP Semantics

  Defines the base concepts QUERY builds on: safety, idempotency, conditional requests, and response status semantics.
• 6
  RFC 9651 — Structured Field Values for HTTP

  The encoding format used by the new Accept-Query header field.
• 7
  expressjs/express #5615 — Support HTTP QUERY method

  Tracks first-class QUERY routing support in Express; current state of manual workarounds.
• 8
  nodejs/node #51562 — Support for 'QUERY' method

  Node.js core tracking issue; confirms QUERY method support landed in the 21.x line.
• 9
  DEV Community: HTTP Just Got Its First New Method in 20 Years

  Accessible practitioner write-up covering ecosystem/adoption context (nginx, Apache, CDNs).
• 10
  Hive Security: RFC 10008 and the Attack Surface Still Catching Up

  Security-focused analysis of QUERY's new risk surface — cache normalization, WAF gaps, injection concerns.