RFC 10008: The HTTP QUERY Method — 16 Years Without a New Verb, Finally Over

The HTTP QUERY method (RFC 10008) is the first new standard HTTP verb since PATCH in 2010. It solves a problem developers have wrestled with for decades: how to send rich query parameters in a request body without sacrificing the safe, idempotent semantics that GET provides.

Diagram of the TCP/IP protocol suite between two Internet hosts linked by routers, with HTTP in the application layer, where QUERY joins as a new method.
Feature image: Kbrose / CC BY-SA 3.0 / Wikimedia Commons.

The first new HTTP verb since 2010 finally lands: QUERY gives you read semantics with a request body, ending the decades-long compromise between GET's URL length limits and POST's state-change baggage. This post breaks down what it is, where it fits in the ecosystem, and what's blocking widespread adoption.

What exactly is the HTTP QUERY method?

QUERY is safe and idempotent like GET, but unlike GET it carries a request body. It sits between GET (read-only, URL-based params) and POST (body-carrying, non-safe/non-idempotent), giving you the best of both worlds for complex queries.

Sources: RFC 10008: The HTTP QUERY Method · RFC 9110: HTTP Semantics

Opening Summary

After 16 years without a new HTTP verb, RFC 10008 introduces QUERY — a safe, idempotent method that carries a request body. It finally gives developers a proper alternative to smuggling complex queries into GET URLs or accepting POST's state-change assumptions. Here's how it works, why it matters, and where the ecosystem stands today.


The Problem HTTP Has Been Avoiding Since 1996

Every developer who's built a search API, a filter endpoint, or a reporting dashboard has hit this wall:

GET /api/articles?filter[status]=published&filter[published_after]=2024-01-01&sort=-date&page[size]=50&page[number]=3&include=author,comments,tags HTTP/1.1

URLs have length limits — not hard protocol limits, but practical ones. Browsers cap them around 8 KB, servers enforce their own (Apache defaults to 8 KB, Nginx to 4 KB via large_client_header_buffers), and proxies add more constraints. Beyond that, query strings leak into access logs, browser history, proxy caches, and analytics — a privacy and observability nightmare for anything involving PII or sensitive filters.

The workaround has always been POST:

POST /api/articles HTTP/1.1
Content-Type: application/json

{ "filter": { "status": "published", "published_after": "2024-01-01" }, "sort": "-date", "page": { "size": 50, "number": 3 } }

But POST carries baggage. It's neither safe nor idempotent by definition. Browsers show "Confirm Form Resubmission" on refresh. Load balancers treat it as a state-changing operation. CDNs won't cache it. Monitoring tools flag it as a write. And the semantic mismatch is jarring: you're reading data, not writing it.

This has been an open wound in web architecture since the early days of HTTP. Asbjørn Ulsberg reopened the conversation at the 2019 HTTP Workshop, and the IETF's HTTPBIS working group took it up with the draft safe-method-w-body. The result is RFC 10008, published in June 2026 — the first new standard HTTP method since PATCH landed in 2010.


What QUERY Actually Is

RFC 10008 defines QUERY as a safe and idempotent request method that carries enclosed content:

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

q=foo&limit=10&sort=-published

Or with JSON:

QUERY /api/search HTTP/1.1
Host: example.org
Content-Type: application/json

{ "query": { "match_all": {} }, "aggs": { ... }, "from": 0, "size": 25 }

The key properties:

  • Safe: Like GET and HEAD, QUERY must not modify the state of the target resource. The server cannot create, update, or delete data in response to a QUERY request.
  • Idempotent: Multiple identical QUERY requests produce the same result. Clients can safely retry them after connection failures without risk of partial state changes.
  • Cacheable: Because it's safe and idempotent, intermediate caches (CDNs, reverse proxies, browser caches) can store and serve QUERY responses — but only for that specific request URI and body combination.
  • Body-carrying: Unlike GET, QUERY carries its query parameters in the request body with a proper Content-Type, enabling arbitrarily complex nested structures.

The method identifier is distinct across all HTTP versions:

  • HTTP/1.x: QUERY in the request line
  • HTTP/2: Method index 28 (:method: QUERY)
  • HTTP/3: Same as HTTP/2

QUERY vs GET vs POST — The Comparison

Property GET QUERY POST
Safe Yes Yes Potentially no
Idempotent Yes Yes Potentially no
URI carries query Yes (by definition) Optional (Location response) No
Body carries query No ("no defined semantics") Expected (semantics per target resource) Expected
Cacheable Yes Yes Only for future GET/HEAD
Browser retry warning No No Yes (form resubmission)
CDN caching Automatic Requires body-aware cache Rarely supported

The sweet spot is clear: QUERY gives you the semantics of a read operation with the payload flexibility of POST.


Real-World Use Cases

1. Elasticsearch-Style Search APIs

Elasticsearch has used POST for search queries since day one because GET URLs can't express complex JSON queries. With QUERY, this becomes semantically correct:

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

{
  "query": { "bool": { "must": [...], "filter": [...] } },
  "aggs": { "categories": { "terms": { "field": "category" } } },
  "from": 0, "size": 50
}

2. GraphQL Over HTTP (Without the Mutation Confusion)

GraphQL already uses POST for queries because the spec requires a body. QUERY makes this semantically honest — you're querying, not mutating.

3. Complex Filtering in REST APIs

Reporting endpoints with multi-dimensional filters (date ranges, categories, tags, custom attributes) no longer need URL-encoded query strings or POST workarounds:

QUERY /api/reports/sales HTTP/1.1
Content-Type: application/json

{
  "dimensions": ["region", "product_category"],
  "filters": {
    "date_range": { "start": "2024-01-01", "end": "2024-12-31" },
    "status": ["active", "pending"]
  },
  "metrics": ["revenue", "units_sold"],
  "group_by": "month"
}

4. Database Query Builders

ORM query builders and database abstraction layers that currently serialize queries to POST bodies can now use QUERY with correct semantics, enabling proper caching and automatic retries.


The Catch: Body-Aware Caching

This is where RFC 10008 hits the hardest real-world friction point. QUERY's cacheability depends on body-aware caching — the ability of an intermediate cache to compute a cache key that includes the request body, not just the URI.

Standard HTTP/1.x caches (and many HTTP/2 implementations) key off method + URI only. A QUERY request to /api/search would be cached by URI alone, ignoring the body — returning stale results for different queries hitting the same endpoint.

The fix requires:

  1. The cache to recognize QUERY as a cacheable method (not just GET/HEAD)
  2. The cache to include the request body in its hash/key computation
  3. Proper Vary header handling when different bodies produce different results

This is analogous to how POST caching works in nginx (proxy_cache_methods POST with $request_body as part of the key), but QUERY has far less infrastructure support at this point.


Ecosystem Adoption — October 2026

RFC 10008 was published on June 15, 2026. As of today (+128 days), here's the landscape:

Servers That Accept QUERY

Stack Status Notes
Apache Tomcat 12.0 ✅ Full support Only server with dedicated doQuery() Servlet API method (Servlet 6.2). QUERY is a first-class method in Method.java.
FastAPI / Starlette ✅ Pass-through QUERY routes work via standard api_route — no special decorator needed, but no auto-generated OpenAPI spec entry yet.
H2O ✅ Pass-through Accepts and forwards QUERY without explicit configuration. No dedicated caching support.
Node.js (undici/http) ⚠️ Partial Raw net/http passes unknown methods through; undici has limited recognition.

Proxies & Load Balancers

Stack Status Notes
Envoy ✅ Merged (+69 days) QUERY support merged to main behind feature flag, default on. First mainstream proxy — but not yet in a stable release (v1.39.3 is latest; v1.40-dev has it).
Skipper (Zalando) ✅ Released (+100 days) Shipped in v0.28.7 with MethodQuery constant, metrics labels, and API monitoring support.
http-proxy-middleware ✅ Merged (+19 days) Node reverse-proxy middleware covers QUERY proxying with tests.
nginx 1.24/1.26 ⚠️ Open PRs Two PRs (#1488, #1511) add basic method recognition and limit_except support. No body-aware caching yet. proxy_cache_methods QUERY currently rejects the config.
Traefik ⚠️ Partial (+100 days) Metrics-labeling PR merged; QUERY is not counted as _unknownmethod_. Forwarding and body-keyed cache not yet implemented. Latest v3.7.14 doesn't include it.
Kong ⚠️ Silent Open discussion #14944 (+34 days), zero maintainer responses after 81 days.
Caddy ❓ Unknown Built on Go's net/http — raw QUERY likely passes through, but no explicit tracking or tests found.
HAProxy ⚠️ Pass-through ACLs with acl is_query method QUERY work for routing. No body-aware cache support.

CDNs & Edge Platforms

Platform Status Notes
Cloudflare workerd ⚠️ Open issue Issue #6849 (+14 days) tracking body-keyed QUERY caching via Cache API. Idle since +18 days.
Varnish ❓ Unknown No public tracking. POST caching is possible with vmod_bodyaccess; QUERY would need VCL customization.
Apache Traffic Server ❌ Fork only QUERY support exists only in a contributor's fork (+69 days). Not proposed upstream.
Managed CDNs (CloudFront, Fastly, Akamai) 🔒 Opaque Hard to track via public repos; verify per product documentation.

The Browser Gap

Browsers have no implementation of QUERY support in the Fetch API (whatwg/fetch#1938). This means client-side code cannot issue QUERY requests today — you'll need a polyfill, server-side proxying, or a migration period where clients use POST with X-Http-Method-Override: QUERY headers.


Migration Strategy

For teams considering QUERY adoption:

Phase 1: Pass-Through (Now)

Deploy QUERY to your origin servers (Tomcat, FastAPI, etc.) behind nginx or HAProxy. The proxy will forward the request even without explicit QUERY support — it's treated as an unknown method and passed through.

Phase 2: Recognition (+6-12 months)

Upgrade proxies to versions that recognize QUERY in limit_except, method allow-lists, and access controls. This prevents QUERY from being blocked by default deny rules or logged as _unknownmethod_.

Phase 3: Body-Aware Caching (+12-18 months)

When Envoy v1.40+, nginx (with body-keyed cache support), and other proxies ship proper QUERY caching, enable it for high-volume query endpoints. This is where the real performance gains materialize.

Phase 4: Client Migration (Ongoing)

Gradually replace POST-based query patterns with QUERY in client libraries. Use feature detection or a method-override header during the transition period.


Security Considerations

QUERY's safety guarantees are a double-edged sword:

Pros:

  • Automatic retries don't risk partial state changes (unlike POST)
  • Load balancers and CDNs can safely cache without invalidation concerns
  • Monitoring tools won't flag QUERY as a write operation, reducing alert noise

Cons:

  • Cache poisoning risk: If the body isn't properly included in the cache key, different queries collide. This is the same risk POST caching has always carried.
  • Bypass attacks: An attacker who knows an endpoint accepts QUERY might bypass authentication rules that only check POST/PUT — if access controls aren't method-agnostic.
  • Body size abuse: Unlike GET (where URL length limits provide a natural cap), QUERY bodies have no inherent size limit. Servers must enforce Content-Length or Transfer-Encoding limits to prevent DoS via oversized query payloads.

The Bigger Picture: Why This Matters

QUERY isn't just another method addition. It resolves a tension that's existed since the first HTTP specification: the separation of semantics from transport.

For 30 years, we've been forced to choose between:

  • GET with URL-encoded params (correct semantics, limited payload)
  • POST with a body (unlimited payload, wrong semantics)

QUERY breaks this false dichotomy. It says: you can have both correct read semantics and a rich request body.

This matters for:

  • API design: REST APIs that use POST for queries are semantically incorrect. QUERY fixes this.
  • Observability: QUERY requests can be cleanly categorized as reads in APM tools, log aggregators, and cost dashboards.
  • Performance: Proper caching of complex queries eliminates redundant origin hits.
  • Developer experience: No more "is this a read or a write?" debates over HTTP method choice.

What To Watch Next

  1. nginx body-aware QUERY caching — PRs are open but idle. The first proxy to ship this will be a major catalyst.
  2. Browser Fetch API support — without client-side QUERY, adoption will be slow. The WHATWG issue is the blocker.
  3. OpenAPI/Swagger spec extensions — QUERY needs native method support in API documentation tools to avoid being documented as a POST workaround.
  4. Cloudflare Workers / Edge Functions — if Cloudflare implements body-keyed QUERY caching, adoption could accelerate rapidly given their developer reach.
  5. GraphQL over QUERY — the GraphQL Foundation may adopt QUERY as the default HTTP method for queries (currently POST-only by spec).

TL;DR

  • QUERY is a safe, idempotent HTTP method that carries a request body (RFC 10008, June 2026)
  • It's the first new HTTP verb since PATCH (2010), 16 years later
  • It solves the GET-vs-POST dilemma: read semantics with body flexibility
  • Server support is emerging (Tomcat has full doQuery() API; FastAPI passes through)
  • Proxy/cache support is fragmented — Envoy merged, nginx has open PRs, many still pass-through
  • Browser Fetch API has no QUERY support yet — this is the biggest adoption blocker
  • Body-aware caching is the technical prerequisite for real performance gains
  • Migration: start with pass-through, upgrade proxies as they support QUERY, migrate clients gradually

The method exists. The spec is ratified. The infrastructure is catching up. The question isn't if QUERY will be widely adopted — it's how fast the ecosystem can build the caching layer that makes it worth using.

Feature image: Kbrose / CC BY-SA 3.0 / Wikimedia Commons.