If you build APIs, you already speak fluent GET, POST, PUT, PATCH, and DELETE. You also, almost certainly, have a POST /search endpoint somewhere in your codebase that doesn’t create anything — it just reads data with a filter body too big to fit in a URL. We’ve all shipped that endpoint. We all knew it was a lie.
In June 2026, the IETF published RFC 10008 — The HTTP QUERY Method, and that lie finally has an honest replacement. It’s the first genuinely new general-purpose HTTP method to reach Proposed Standard since PATCH landed back in 2010 — roughly sixteen years of standing still.
This post walks through what the spec actually says, why both GET and POST fall short for real queries, the genuinely clever part most summaries skip (stored queries vs stored results), how to send a QUERY request from TypeScript today, and — just as important — the limits you need to respect before you put it anywhere near production.
The situation: reading data is messier than it looks
The canonical “read with parameters” request is a GET with a query string:GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 Host: example.org
This is semantically perfect. The resource is fully described by the URI, so caching and retries “just work.” The trouble starts the moment your query stops being trivial.
RFC 10008 calls out four concrete failure modes for cramming queries into the URI:
- Size limits are unknowable in advance. A request can pass through many uncoordinated proxies, CDNs, and gateways. RFC 9110 only recommends supporting at least 8000 octets as a floor — it’s not a ceiling you can rely on.
- Encoding structured data into a URI is wasteful and ugly. Nested filters, arbitrary JSON, or a JSONPath expression become an unreadable, percent-encoded mess.
- URIs get logged and bookmarked. Query parameters end up in access logs, browser history, and analytics — a real problem when the filter contains anything sensitive.
- Every input combination becomes a distinct “resource.” Cache entries and URIs explode combinatorially when the query is really just a parameter set.
The complication: so we all reached for POST
To dodge those problems, the industry defaulted to POST:POST /feed HTTP/1.1 Host: example.org Content-Type: application/x-www-form-urlencoded q=foo&limit=10&sort=-published
The body solves the size and encoding problems. But POST throws away everything that made GET nice:
- It isn’t safe. Nothing in the protocol tells an intermediary that this request only reads. Caches won’t touch it, and monitoring tools assume it mutates state.
- It isn’t idempotent. If the connection drops mid-flight, a client can’t safely replay it, because a generic
POSTmight have changed something. - Everyone reinvents the wheel. Each framework grows its own ad-hoc “this POST is actually a safe read, trust me” convention.
So we’ve spent years with two tools, each missing exactly the half we needed.
The question: can one method be safe like GET and carry a body like POST?
That’s precisely the gap QUERY is designed to fill.
The answer: QUERY — a safe, idempotent request with a body
Straight from the RFC 10008 abstract: a QUERY request asks the target resource to process the enclosed content in a safe and idempotent manner and respond with the result. The same query as above becomes:
QUERY /feed HTTP/1.1 Host: example.org Content-Type: application/x-www-form-urlencoded q=foo&limit=10&sort=-published
Like POST, the input lives in the request body. Unlike POST, the method is explicitly safe and idempotent — which is the whole point. That single guarantee is what unlocks caching, automatic retries, and sane behavior from every proxy in the chain.
Here’s how the three methods line up, following the property table in the RFC: Property GETQUERYPOST Safe Yes Yes Potentially no Idempotent Yes Yes Potentially no Request body No defined semantics Expected Expected Cacheable Yes Yes Only for a future GET/HEAD URI for the query itself Yes (by definition) Optional (Location) No URI for the query result Optional (Content-Location) Optional (Content-Location) Optional (Content-Location)
QUERY sits deliberately in the middle: the ergonomics of POST with the semantics of GET.
Anatomy of a QUERY request
A complete round-trip looks like this:
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="email=*@example.*"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" } ]
Two rules worth burning into memory:
Content-Typeis mandatory. The server must fail the request ifContent-Typeis missing or inconsistent with the body. The media type is the query language —application/sql,application/jsonpath,application/x-www-form-urlencoded, XSLT, whatever the resource supports.- No content sniffing. A server is not allowed to guess the media type from the body and “fix” a wrong header. If you claim
application/jsonbut send SQL, that’s a400, not a favor.
The spec maps failure cases to specific status codes, which is handy when designing error handling:
- Missing media type →
400 Bad Request - Media type not supported by the resource →
415 Unsupported Media Type - Header inconsistent with the actual body →
400 Bad Request - Valid syntax but the query can’t be fulfilled (e.g. correct SQL naming a table that doesn’t exist) →
422 Unprocessable Content - Requested response type (
Accept) not supported →406 Not Acceptable
The genuinely clever part: two different URIs
Most write-ups stop at “GET with a body.” The richer idea in RFC 10008 is that a successful QUERY response can hand you back URIs — and there are two distinct kinds, which are easy to confuse.HTTP/1.1 200 OK Content-Type: application/json Content-Location: /contacts/stored-results/17 Location: /contacts/stored-queries/42 [ ... the results ... ]
Content-Location→ the frozen result. AGET /contacts/stored-results/17gives you back this specific result set, as it was computed. Think of it as a snapshot. It may be temporary.Location→ the re-runnable query. AGET /contacts/stored-queries/42re-executes the same query against current data — without you resending the body. It’s a saved query, not a saved answer.
That distinction is powerful in practice:
- Share a query with a teammate by sending them a short link instead of a giant filter payload.
- Bookmark a search that stays live.
- Let a cache or CDN key off the query, then switch subsequent calls to plain
GETon theLocationURI — which sidesteps the awkwardness of caching a request that has a body.
It also plays nicely with conditional requests. Once you have that Location URI, a follow-up GET with If-None-Match or If-Modified-Since returns a clean 304 Not Modified when nothing changed — no body resent, no results recomputed.
Discovering support: OPTIONS and Accept-Query
Because adoption is uneven, discovery matters. Two mechanisms from the spec:OPTIONS /contacts HTTP/1.1 Host: example.orgHTTP/1.1 200 OK Allow: GET, QUERY, OPTIONS, HEAD
The Allow header tells you the method exists. To learn which query formats a resource accepts, RFC 10008 introduces a new response header, Accept-Query:Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"
Note that Accept-Query is a Structured Field (RFC 9651), not a plain comma list like Accept. It looks similar but must be parsed as a structured field — a subtle gotcha for anyone writing a client.
Try it in TypeScript today
Here’s the honest, practical part. Node.js has been able to parse the QUERY method for a while, and modern fetch() accepts it as a custom method string. The examples below were run on Node.js v22 — a tiny server that speaks QUERY, plus two clients hitting it. This actually executes.
A minimal QUERY-aware server (Node http)
import http from "node:http";
const server = http.createServer((req, res) => {
if (req.method === "QUERY" && req.url === "/contacts") {
// RFC 10008 §2.1: Content-Type is required for QUERY.
if (!req.headers["content-type"]) {
res.writeHead(400, {
"Content-Type": "application/json",
});
return res.end(
JSON.stringify({
error: "Content-Type required",
})
);
}
let body = "";
req.on("data", (chunk) => {
body += chunk;
});
req.on("end", () => {
// ...parse `body` as your query language and run a READ-ONLY query...
const results = [
{
surname: "Smith",
email: "smith@example.org",
},
{
surname: "Dubois",
email: "camille@example.net",
},
];
res.writeHead(200, {
"Content-Type": "application/json",
// Optional: a re-runnable URI for the same query (RFC 10008 §2.4)
Location: "/contacts/stored-queries/42",
});
res.end(JSON.stringify(results));
});
return;
}
if (req.method === "OPTIONS") {
res.writeHead(200, {
Allow: "GET, QUERY, OPTIONS, HEAD",
});
return res.end();
}
res.writeHead(405, {
Allow: "GET, QUERY, OPTIONS, HEAD",
});
res.end("Method Not Allowed");
});
server.listen(3000);
Client A — the built-in http module
import http from "node:http";
const payload =
"select=surname,email&limit=10&match=email=*@example.*";
const req = http.request(
"http://127.0.0.1:3000/contacts",
{
method: "QUERY",
headers: {
"Content-Type": "application/x-www-form-urlencoded",
Accept: "application/json",
},
},
(res) => {
let data = "";
res.on("data", (chunk) => {
data += chunk;
});
res.on("end", () => {
console.log("status:", res.statusCode);
console.log("location:", res.headers.location);
// /contacts/stored-queries/42
console.log("body:", data);
});
}
);
req.write(payload);
req.end();
Client B — fetch() with a structured body
const res = await fetch("http://127.0.0.1:3000/contacts", {
method: "QUERY",
headers: {
"Content-Type": "application/json",
Accept: "application/json",
},
body: JSON.stringify({
role: "admin",
sort: "name",
page: 1,
}),
});
console.log("status:", res.status); // 200
console.log("location:", res.headers.get("location")); // /contacts/stored-queries/42
console.log("results:", await res.json());
Both clients returned 200, the JSON results, and the Location header exactly as expected. RequestInit.method is typed as a plain string, so method: "QUERY" type-checks without any casting — no @ts-expect-error gymnastics required.
A note on frameworks: raw Node works, but higher-level routers lag. Express doesn’t expose an
app.query()router method, so today you’d branch onreq.method === "QUERY"inside middleware. On the JVM side, Spring’s support was still an open pull request as of mid-2026 — itsRequestMethodenum didn’t yet includeQUERY, so@RequestMappingcouldn’t route it. Always check your specific framework’s changelog rather than assuming.
The limits — read this before shipping it
QUERY is a clean, well-designed primitive. It is not a drop-in you sprinkle over production tomorrow. Here’s where reality bites.
1. Tooling and intermediary support is still catching up. A method standardized in June 2026 has to earn its place across browsers, proxies, load balancers, API gateways, and corporate firewalls. Many of these enforce method allowlists written years ago that only know GET/POST/PUT/DELETE/PATCH. An unrecognized QUERY may be silently dropped, rejected with a 405, or — worse — routed and inspected as though it were a POST.
2. Browsers require a CORS preflight. QUERY is not on the CORS-safelist. Any cross-origin QUERY from browser JavaScript triggers a preflight OPTIONS round-trip, and your server must answer it correctly (Access-Control-Allow-Methods: QUERY). Miss that and the request never leaves the browser.
3. The cache key includes the body — which is subtle and risky. RFC 10008 requires the cache key to incorporate the request content. That’s what makes caching-with-a-body possible, but it means caches have to read and sometimes normalize the body to build a key. Normalize it differently from how your server interprets it and you get a false-positive cache hit — the classic setup for cache poisoning or cache deception. This is meaningfully harder than caching a GET, where the URI is the whole key.
4. “Safe” is an HTTP contract, not an infrastructure guarantee. Safe means the client doesn’t request or expect a change to the target resource’s state. It does not mean zero cost. Your server may still hit read replicas, generate real database load, rack up billing, and — legitimately — create temporary stored-query or stored-result resources. Don’t confuse “safe” with “free.”
5. Sensitive data needs deliberate handling. One of QUERY‘s selling points is keeping sensitive filters out of URLs (and therefore out of logs). But if your server mints a Location or Content-Location URI for a stored query, the RFC is explicit: that URI must not embed sensitive parts of the original request. It’s easy to leak in the very field meant to help you.
6. Strictness around Content-Type. No header, or a header that disagrees with the body, is a hard failure by design. That’s good hygiene, but it means sloppy clients that got away with vague POST bodies will break.
So — should you use it yet?
The pragmatic rollout the community converged on is additive, not replacement:
- Add
QUERYalongside your existingPOST /searchendpoint, don’t rip the old one out. - Advertise support with
Accept-Queryand honestOPTIONS/Allowresponses so clients can feature-detect. - Let clients migrate as their HTTP stacks, CDNs, and gateways gain support.
- Audit the middle — WAF rules, cache configs, CORS policy, and CSRF assumptions — so
QUERYis handled deliberately rather than by accident.
For now, treat it as an architecture decision to plan for, not a hotfix to deploy on a Friday.
Conclusion
QUERY is a small addition with an outsized payoff: it retires a workaround the web has leaned on since the late ’90s. It gives search-shaped endpoints a method that is safe, idempotent, cacheable, and body-carrying — no more pretending a POST is a read. The concept is final and the primitive is right; what remains is the slow, unglamorous work of ecosystem support.
Understand it now, prototype with it in Node or your API layer, design your next API with it in mind — and roll it out in production once the infrastructure around you has caught up.
Further reading
- RFC 10008 — The HTTP QUERY Method (the primary source; the examples and status codes above all trace back here)
- RFC 9110 — HTTP Semantics (safe, idempotent, and the 8000-octet recommendation)
- RFC 9651 — Structured Field Values for HTTP (how
Accept-Queryis parsed)
Enjoyed this? I write about full-stack development, GIS, and web mapping. Let’s connect:
- 🌐 Portfolio: rz-codes.com
- ✍️ Blog: blog.rz-codes.com
- 🐙 GitHub: github.com/rabira-hierpa
- 🐦 X / Twitter: @rzcodes
- 💼 LinkedIn: Rabira
- 📺 YouTube: @rzcodes
- 👨💻 Dev.to: @rzcodes
Comments
Sign in with GitHub to comment or react. Threads live in GitHub Discussions, so you can also reply from GitHub.