IETF publishes HTTP QUERY (RFC 10008) to enable safe, cacheable read requests with bodies

Why HTTP QUERY? Understanding the New HTTP Method for Modern API Design

when building web APIs, choosing the correct HTTP method is an important part of API design. For many years, developers have mainly used GET to retrieve data and POST to send data to the server. These methods work well for most applications, but they also have limitations. Modern applications often need to perform complex searches with multiple filters, sorting options, and advanced conditions. In these situations, developers usually have to choose between using a long GET URL or using POST for a read-only operation. To solve this problem, the Internet Engineering Task Force (IETF) introduced a new HTTP method called QUERY in RFC 10008, published in June 2026. It's the first new HTTP method to become an official standard in more than two decades. In this article, we'll explore what the HTTP QUERY method is, why it was introduced, and how it can improve API design. The Challenge with GET Requests GET is the standard HTTP method used for retrieving information from a server. For example, a user searching for action movies released in 2025 can send a simple GET request: GET /movies?genre=Action&year=2025 This approach works well because the request is short and easy to understand. However, modern applications often require more advanced search options. Imagine a user wants to find movies with these conditions: Genre: Action or Adventure Language: English Rating above 8 Released after 2020 Available for streaming Sorted by rating Representing all these conditions in a URL can make the request very long and difficult to manage. A complex GET request may look like this: GET /movies?genre=Action&genre=Adventure&language=English&rating=8&year=2020&streaming=true&sort=rating As the number of filters increases, URLs become harder to read, maintain, and process. Why Developers Use POST for Searching To avoid long URLs, developers often use POST requests for complex searches. POST /movies/search Content-Type: application/json { "genres": ["Action", "Adventure"], "language": "English", "minRating": 8, "releasedAfter": 2020, "streaming": true, "sortBy": "rating" } This approach is cleaner because the search criteria are sent inside the request body. However, POST is mainly designed for operations that create or modify resources, such as: Creating a new account Uploading files Updating information Although a search request using POST does not modify data, the HTTP method itself does not clearly communicate that it is a read-only operation. POST and QUERY Can Look the Same — So What's the Real Difference? Here is where many readers get confused: a POST request and a QUERY request can have the exact same body. Look at these two requests: POST /movies/search Content-Type: application/json { "genres": ["Action", "Adventure"] } QUERY /movies Content-Type: application/json { "genres": ["Action", "Adventure"] } The JSON inside is exactly the same. So if you only look at the body, you can't tell these two requests apart. Then why do we need two different methods? Because the body is not what carries the meaning. The method name carries the meaning. The body just holds the data. The method tells the server what to do with that data. Think of the method name as a label on a box, not what's inside the box: POST means: "Do something with this — it might create, change, or update something. Don't repeat this request automatically, since repeating it could cause problems." QUERY means: "Just read this and send back an answer. Nothing will change. It's safe to repeat, and safe to save (cache) the response." This label matters, even when the data is the same, because other tools read the method name and act on it — without ever looking inside the body: Caches and CDNs don't save (cache) POST responses, since POST might change something. But they can safely save a QUERY response, since QUERY promises not to change anything. Browsers won't automatically resend a failed POST request, because resending it could do something twice (like creating two accounts by mistake). A failed QUERY can be resent safely, since it never changes data. Other developers reading your API can understand what an endpoint does just from its method name. POST /movies/search doesn't tell you if it's a search or a change — you'd have to check the code. QUERY /movies tells you right away: this only reads data. So the identical body is not a problem — it's actually the reason QUERY needed to exist. If POST and QUERY could never look the same, there would be no confusion, and no need for a new method. QUERY exists to remove that confusion, so a read-only request no longer has to borrow POST just to send a body. Introducing the HTTP QUERY Method The HTTP QUERY method was introduced to fill this gap. QUERY combines the advantages of GET and POST: Like POST, it supports a request body. Like GET, it represents a safe, read-only operation — and it's cacheable, so proxies and CDNs can cache a QUERY response the same way they'd cache a GET. The previous movie search can be written using QUERY: QUERY /movies Content-Type: application/json { "genres": ["Action", "Adventure"], "language": "English", "minRating": 8, "releasedAfter": 2020, "streaming": true, "sortBy": "rating" } This request clearly communicates its purpose: the client wants to retrieve data based on specific conditions without changing anything on the server. GET vs POST vs QUERY Method Body support Safe / read-only Cacheable Best for GET No (query params only) Yes Yes Simple retrieval POST Yes No No Creating/updating resources QUERY Yes Yes Yes Complex read-only operations Summary: GET is best for simple data retrieval where query parameters are enough. POST is useful when sending large amounts of data or creating/updating resources. QUERY is designed for complex read-only operations where a request body is required. ## Why Is QUERY Important? Supports Complex Data Structures Developers can send structured data such as JSON objects, arrays, and nested filters instead of creating complicated URLs: { "filters": { "rating": 8, "year": 2025 }, "sort": "rating" } This makes complex requests easier to understand and maintain, and gives developers a standard way to handle advanced search requirements without misusing other HTTP methods. Improves API Clarity The HTTP method itself describes the purpose of the request. A developer reading: QUERY /movies can immediately understand that the operation is intended for retrieving information. Real-World Use Cases The QUERY method can be useful in applications that require complex read operations, such as: Movie and streaming platforms Online shopping applications Travel booking systems Library management systems Employee management systems Analytics dashboards and reporting applications For example, an analytics dashboard may need to retrieve data based on multiple date ranges, different user groups, several filtering conditions, and custom sorting rules. A QUERY request can represent all of this clearly in a single, structured body. Conclusion The HTTP QUERY method provides a standard way to perform complex read-only operations using a request body. It combines the flexibility of POST with the safe semantics of GET, making APIs clearer and more expressive. Although adoption will take time, QUERY is a valuable addition to modern API design.

2 hours ago

HTTP QUERY Is Here — And Your Infrastructure Isn't Ready For It

HTTP QUERY Is Here — And Your Infrastructure Isn't Ready For It In June 2026, the IETF published RFC 10008, standardizing a new HTTP method: QUERY. It's the first new standard HTTP method since PATCH in 2010, and it fixes a compromise developers have lived with for 16+ years: how do you send a large, structured, read-only request without abusing POST? QUERY combines: Safe — no state change on the server Idempotent — repeat it, get the same result Cacheable — like GET Has a request body — like POST QUERY /orders HTTP/1.1 Host: api.example.com Content-Type: application/json Accept: application/json { "status": "active", "filters": { "region": "eu", "amount_gt": 500 } } Notably, Cloudflare and Akamai engineers co-authored the RFC alongside Julian Reschke — a strong signal that edge/CDN support is coming faster than framework support. Below: the three questions actually worth debating right now. 1. Caching: Solved in Spec, Unsolved in Practice With GET, the cache key is just the URL. With QUERY, the cache key must incorporate the request body, since the "identity" of the request now lives partly in the payload. This creates real engineering work for caching layers: The proxy/CDN must buffer the body before it can even compute a cache key It must hash the body alongside the URI It should ideally normalize semantically-identical payloads (e.g., whitespace or key-order differences in JSON) so equivalent queries hit the same cache entry — otherwise cache hit rates collapse This isn't hypothetical difficulty — it's exactly the gap that exists in current CDN cache-key implementations today. Cloudflare Workers' cache key, for example, is built from path and query string; request bodies do not currently partition the cache because only GET/HEAD are cacheable in existing implementations. QUERY breaks that assumption entirely, and CDNs will need dedicated logic before QUERY caching is trustworthy in production. Bottom line: QUERY can be cached correctly per spec, but until CDNs ship QUERY-aware cache-key logic, treat "QUERY is cacheable" as a promise, not a guarantee your edge layer honors today. 2. Why WAFs and Security Layers Flag QUERY as Malicious This is the most immediate real-world pain point. Reasons boil down to: Method allowlists predate the RFC. WAFs, API gateways, and load balancers typically enumerate accepted methods (GET, POST, PUT, DELETE, PATCH). An unrecognized method often gets rejected outright, or worse, misrouted. QUERY looks like an anomaly to signature-based rules. A "GET-like" request carrying a JSON body doesn't match existing heuristics tuned to associate bodies with mutation, so some systems flag it as suspicious traffic or a protocol violation. CORS treats it as non-safelisted. QUERY is not a CORS-safelisted method, meaning browser JavaScript must trigger a preflight OPTIONS request — infrastructure that doesn't expect QUERY may not handle that preflight correctly either. CSRF middleware assumptions break. Libraries that assume "safe methods = no body = no CSRF risk" now have a method that's safe and carries a body, which some implementations weren't designed to reason about. Practical takeaway: before adopting QUERY, audit — don't assume — how your WAF, gateway, CDN, and CSRF middleware treat unrecognized methods. Some will drop it silently, which is worse than an explicit rejection. 3. Architectural Benefits Over POST-for-Search Moving from POST /search to QUERY /search isn't cosmetic — it restores semantics the protocol actually enforces: POST-for-read QUERY Cacheable No (POST responses aren't cached by default) Yes, by spec Safe/idempotent Not signaled to intermediaries Explicit Auto-retry on failure Unsafe to assume Safe by definition Redirect behavior 301/302 often converts to GET and drops the body 301/302/307/308 preserve the method and body Browser/proxy semantics Assumed mutation Correctly identified as a read The GraphQL ecosystem is the clearest beneficiary — GraphQL has used POST for all operations (including reads) purely to carry a body, sacrificing HTTP-level caching and safe retries in the process. QUERY gives that read path a semantically correct home without changing the query language itself. For REST APIs with complex filter/search payloads (nested objects, arrays, boolean logic), QUERY also removes the need to cram parameters into URLs, which historically broke on length limits (varying wildly across browsers/proxies, often 2–8KB) and leaked sensitive parameters into logs and browser history. Should You Use It in Production Today? Not yet, but start preparing: Spec status: Final (Proposed Standard, RFC 10008) — this isn't a draft anymore Client support: No native fetch() support until WHATWG acts; curl and HTTP libraries are catching up Server frameworks: Early/partial support (e.g., .NET 10 already supports it); most frameworks haven't shipped yet Edge/CDN: Best positioned to move fast given Cloudflare/Akamai authorship, but no confirmed general-availability cache handling yet Action items if you're evaluating QUERY: Watch your framework and CDN changelogs for explicit QUERY support announcements Audit WAF/gateway method allowlists now — don't wait for a 405 in production If you're stuck tunneling GraphQL or complex filters through POST, start scoping the migration path, but keep POST as the production path until infra support is confirmed What's your stack's current behavior when it receives an unrecognized HTTP method — silent drop, 405, or does it pass through? Worth checking before QUERY traffic shows up in the wild.

4 days ago

The New HTTP QUERY Method

If you've ever built a search endpoint, you've hit this wall. Your query has filters, sort orders, a nested set of facets, maybe a geo bounding box. It doesn't fit in a URL, and cramming it into query string params is ugly and fragile. So you reach for POST /search, send the whole thing as a JSON body, and quietly accept that you've just lied about what the request does. It's not creating anything. It's a read. But POST is the only tool that lets you attach a body without fighting the platform. That gap finally got filled. In June 2026 the IETF published RFC 10008, which defines the HTTP QUERY method: a new verb built for exactly this case. The two bad options Every read that needs structured input has been stuck choosing between GET and POST, and both are wrong in their own way. GET is the semantically correct choice. It's safe (the client isn't asking to change anything), it's idempotent (retrying it is fine), and it's cacheable. The problem is the body. RFC 9110 is explicit that content in a GET request has no defined semantics, and sending one may cause some implementations to reject the request. So your query has to live in the URI, where you run into unknown length limits across proxies and servers, encoding overhead, and the query landing in access logs and browser history. POST solves the body problem and creates a new one. It carries any payload you want, but it's neither safe nor idempotent by definition. Intermediaries won't cache it, clients won't retry it automatically after a dropped connection, and anything inspecting traffic has to assume the request might have side effects. You get the body, you lose everything that made the request honest. QUERY is the missing third option: a method that carries a body and keeps the semantics of a read. What QUERY actually is The spec, authored by Julian Reschke, James Snell, and Mike Bishop, describes it in one sentence: A QUERY requests that the request target process the enclosed content in a safe and idempotent manner and then respond with the result of that processing. So a QUERY request looks like this: QUERY /products HTTP/1.1 Host: example.com Content-Type: application/json Accept: application/json { "filters": { "category": "keyboards", "inStock": true }, "sort": [{ "field": "price", "order": "asc" }], "page": { "size": 20 } } The three properties that matter: It's safe and idempotent. The client isn't requesting a state change, and the request can be retried or repeated without worrying about partial effects. This is what POST could never promise. It's cacheable. A cache is allowed to store the response and use it to satisfy later QUERY requests. The catch is that the cache key has to include the request content, not just the URI, since the body is what distinguishes one query from another. Two QUERYs to the same URL with different bodies are different requests. The response isn't a representation of the URI. Unlike GET, where the response is the resource at that URL, a QUERY response is the result of running your query over some data scoped to the target. GET /products returns the products resource; QUERY /products returns whatever your query selected from it. The details that bite A few rules are worth knowing before you wire this up. Content-Type is mandatory. The server MUST reject the request if the Content-Type field is missing or inconsistent with the body. In practice you'll see a 400 for a missing media type, a 415 Unsupported Media Type for one the server doesn't handle, and a 422 Unprocessable Content when the body parses fine but doesn't make sense as a query. There are two response headers that trip people up because they sound alike: Content-Location points at a resource representing the results of this query. A client can GET that URL later to fetch the same results again. Location points at a resource representing the query itself. A client can GET that URL to re-run the query without resending the body, which is handy for turning a heavy query into a shareable link. Results points to the answer; Location points to the question. The spec also nudges you away from HTTP range requests for pagination. Range semantics technically apply, but most query formats already have their own paging built in (think SQL's FETCH FIRST), and that's the mechanism you should reach for. Can you use HTTP QUERY today? On the client, yes, already. The Fetch API and libraries like axios accept arbitrary method strings, so nothing is stopping you from sending one right now: const res = await fetch("/products", { method: "QUERY", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ filters: { category: "keyboards" } }), }); The friction is everywhere else in the stack. QUERY isn't a CORS-safelisted method, so cross-origin QUERY requests trigger a preflight OPTIONS. Your server has to answer it with Access-Control-Allow-Methods: QUERY or the browser blocks the real request. And anything that whitelists methods will reject QUERY until you tell it not to: reverse proxies, WAFs, API gateways, limit_except blocks in nginx. The method passing through the wire is the easy part; the config that guards the wire is where you'll spend your time. Framework and server support is still landing. New HTTP methods don't come around often. The last one most people reached for was PATCH back in 2010, so the ecosystem moves slowly. Expect native routing helpers and middleware to fill in over the next couple of years rather than overnight. Should you rush to switch? Probably not, and there's no need to. Your POST /search endpoints work and aren't going anywhere. QUERY is the more correct tool, not an urgent migration. What it does give you is a real answer to a question we've been hacking around for years. When you're designing a new read endpoint that needs a structured body, you now have a method that says exactly what it means: this is a safe, repeatable, cacheable read, and here's the query in the body where it belongs. That's worth reaching for on the next thing you build, even if the old endpoints stay put.

4 days ago

Meet HTTP QUERY: The New HTTP Method You've Probably Been Waiting For

For years, developers have faced the same dilemma when implementing complex search APIs: GET is the correct semantic choice for read-only operations, but query parameters can become extremely long and difficult to manage. POST allows sending a request body, but it's intended for operations that may change server state, making it a poor semantic fit for searches. To bridge this gap, the IETF has introduced a new HTTP method: QUERY (RFC 10008). Why was QUERY introduced? Modern APIs often require complex filtering: nested JSON filters GraphQL-like requests advanced search criteria large lists of IDs geospatial or analytical queries Encoding all of this into a URL is cumbersome and can exceed practical URI length limits. Developers have traditionally worked around this by using "POST" for read-only searches. The problem is that "POST" doesn't express the intent of the request very well. The new QUERY method solves this by allowing clients to send a request body while keeping the operation explicitly safe and idempotent. Key benefits ✅ Request body support Unlike "GET", "QUERY" allows sending structured request data in the message body, making complex searches much easier to model. ✅ Safe by design Like "GET", a "QUERY" request must not modify server state. It clearly communicates that the request is read-only. ✅ Idempotent Repeating the same "QUERY" request produces the same result without additional side effects, allowing clients and intermediaries to safely retry requests after transient failures. ✅ Cache-friendly Unlike the common "POST"-for-search pattern, "QUERY" is designed to work with HTTP caching, enabling better performance and more efficient network usage. ✅ Better API semantics Instead of overloading "POST" for read operations, APIs can now express their intent more accurately: "GET" → simple resource retrieval "QUERY" → complex read operations with a request body "POST" → operations that create or modify state Example Instead of forcing everything into a long URL: GET /products?category=laptops&brand=Lenovo&priceMin=1000&priceMax=2500&features=.. you can send: QUERY /products Content-Type: application/json { "category": "laptops", "brand": "Lenovo", "price": { "min": 1000, "max": 2500 }, "features": [ "32GB RAM", "OLED" ] } Final thoughts The new "QUERY" method fills a gap that has existed in HTTP for decades. It combines the best parts of "GET" and "POST": the safety and semantics of a read operation with the flexibility of sending a request body. Whether it becomes widely adopted depends on support from browsers, servers, proxies, API gateways, and frameworks. However, it provides a standardized solution to a problem that many API designers have been solving with "POST" for years. As HTTP continues to evolve, "QUERY" is a small but meaningful addition that makes API design more expressive and semantically correct. References RFC 10008 — The HTTP QUERY Method IETF HTTP Working Group specification

5 days ago