HTTP QUERY Method (RFC 10008): What It Is and How to Test It

For years, API teams have faced the same awkward choice. A search with twenty filters does not fit nicely in a URL, so you either cram it into a giant query string with GET, or you send it as a body with POST and lose everything that makes reads easy: caching, safe retries, and the clear signal that nothing on the server changes.

The HTTP QUERY method fixes that. The IETF published it as RFC 10008 in June 2026, the first new standard HTTP method since PATCH in 2010. This guide explains what QUERY is, how it differs from GET and POST, and, because this is QA Bash, exactly how to test an API that adopts it.

What is the HTTP QUERY method?

QUERY is a request method for read-only operations that carry a body. Like GET, it is safe (it must not change server state), idempotent (sending it twice has the same effect as once) and its responses can be cached. Like POST, the details of the request travel in the body instead of the URL.

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

{ "select": ["id", "email", "total"], "status": ["paid", "refunded"], "limit": 10 }

The server reads the body, runs the query, and returns the matching results. Nothing is created, updated or deleted.

QUERY vs GET vs POST

Property	GET	POST	QUERY
Safe (no state change)	Yes	No	Yes
Idempotent (safe to retry)	Yes	No	Yes
Request body	No defined meaning	Yes	Yes
Cacheable	Yes	Only in narrow cases	Yes, keyed on the body as well
Parameter size	Limited by URL length	Large	Large
Parameters visible in URLs and access logs	Yes	No	No
Typical use	Fetch a resource	Create or trigger an action	Search, filter, report, complex read

The practical wins: complex searches no longer hit URL length limits, sensitive filter values stop leaking into access logs and browser history, and infrastructure can treat the request as a read, so it can cache it and retry it after a network failure.

How a server advertises and answers QUERY

RFC 10008 adds a few details worth knowing before you write tests:

• Accept-Query: a new response header in which a server lists the media types it accepts as QUERY bodies, for example Accept-Query: application/json, application/sql. It tells clients the method is supported on that resource.
• The body defines the query: the request’s Content-Type says how to interpret it. An unsupported type should be rejected, typically with 415 Unsupported Media Type.
• Caching includes the body: a cache may store QUERY responses, but the cache key must take the request content into account, otherwise two different searches could share one cached answer.
• Locations for results: a server can point to a URI where the same results (or the query itself) can be fetched later with a plain GET, using the Location or Content-Location response headers. That makes results bookmarkable and shareable.

Is QUERY supported yet?

The standard is new, so support is uneven. As of October 2026, the Rust http crate has merged support, while ASP.NET Core, Axum, Quarkus and the Bruno API client are tracking it in public issues. Any client that lets you set a custom method can already send QUERY, including curl, Python requests, Playwright and REST Assured.

The weak spot is everything in between. Older proxies, load balancers, API gateways and web application firewalls may reject or mishandle a method they do not recognise. That is exactly where testers earn their keep.

How to test an API that uses QUERY

A QUERY endpoint needs every test you would write for a search API, plus checks for the guarantees the method promises. Here is the test matrix we recommend.

Test	Expected result	Why it matters
Valid QUERY with a supported Content-Type	200 with the matching results	Basic correctness
Same QUERY sent twice	Identical results, no extra writes	Idempotency is a promise, not a hope
Compare database or event log before and after	No change	QUERY must be safe
Unsupported Content-Type	415 Unsupported Media Type	Body format is negotiated
Malformed body	400 with a useful error	Input validation
Very large body	Handled, or 413 Content Too Large	Limits move from the URL to the body
OPTIONS or a probe request	Accept-Query header present where supported	Clients discover support this way
Two different bodies to the same URL through a cache	Different responses	Cache key must include the body
Same body through a cache	Cache hit where configured	Caching actually works
Request through the real gateway, proxy and WAF	Reaches the service unchanged	Infrastructure may block unknown methods
Browser call from another origin	CORS preflight allows QUERY	QUERY is not a CORS-safelisted method
Check access logs	Filter values are not logged	A key privacy benefit over GET

Sending QUERY requests from your test tools

curl

curl -i -X QUERY https://api.example.org/orders 
  -H "Content-Type: application/json" 
  -d '{"status": ["paid"], "limit": 10}'

Python (requests and pytest)

import requests

def test_query_is_idempotent():
    body = {"status": ["paid"], "limit": 10}
    first = requests.request("QUERY", "https://api.example.org/orders", json=body)
    second = requests.request("QUERY", "https://api.example.org/orders", json=body)
    assert first.status_code == 200
    assert first.json() == second.json()

Playwright (TypeScript)

import { test, expect } from "@playwright/test";

test("QUERY rejects unsupported content types", async ({ request }) => {
  const res = await request.fetch("/orders", {
    method: "QUERY",
    headers: { "Content-Type": "text/plain" },
    data: "status=paid",
  });
  expect(res.status()).toBe(415);
});

REST Assured (Java)

given()
    .contentType(ContentType.JSON)
    .body("{"status": ["paid"], "limit": 10}")
.when()
    .request("QUERY", "/orders")
.then()
    .statusCode(200);

When should a team adopt QUERY?

QUERY is a good fit when a read operation has grown too big or too sensitive for a URL: reporting endpoints, advanced search, analytics filters, or any GET that teams quietly turned into a POST. It is not worth migrating simple lookups like GET /orders/123.

Before switching, check every hop between the client and the service. Run the matrix above through staging with production-like infrastructure, because a gateway that silently drops QUERY is the most likely failure. Keep the old POST search alive until monitoring shows clients have moved.

For more on API test design, see our API testing stories, and practise request-level debugging with the free API Workbench.

Bookmark