If you build APIs, you have hit this wall: you need a complex search endpoint. You need to pass nested filters, sort conditions, and pagination cursors.
You have two choices, and they are both bad.
If you use GET, you are semantically correct. It is a read-only operation. It is safe and idempotent. But you have to serialize a massive JSON object into a query string. You hit URL length limits in load balancers (usually around 4KB-8KB). You leak PII into access logs because proxies log the full URI by default.
If you use POST, you get the request body. No URL limits, no PII in the access logs. But you break semantics. POST is explicitly unsafe and non-idempotent. CDNs refuse to cache it. Client libraries won't automatically retry it on network timeouts because retrying a POST might double-charge a credit card or duplicate a record.
For over a decade, we just accepted that POST /search was the ugly compromise.
In June 2026, the IETF finally proposed a standard regarding the HTTP QUERY method (RFC 10008). It fixes the spec. But rolling it out is going to break your infrastructure.
How QUERY fixes the spec
The QUERY method is exactly what you think it is:
A safe and idempotent method that carries its payload in the request body.
It is formally defined as safe and idempotent. This means:
- It can be safely retried: If the TCP connection drops, the client (or the proxy) can retry the request without worrying about side effects.
-
It can be cached: CDNs and reverse proxies know that the response to a
QUERYrequest won't change server state.
Instead of deriving the cache key entirely from the URI (like GET), caches derive the key from the URI plus the request body.
When it works, it is the perfect middle ground. You send a 10KB GraphQL query or a nested JSON filter object in the body, and your CDN caches the response just like a static asset.
Where this breaks in production
The standard is final, but the Internet is built on middleboxes that assume the standard never changes. Every piece of infrastructure between your user and your database was built under the assumption that read-only requests do not have bodies, and body-carrying requests mutate state.
If you deploy a QUERY /api/v1/orders endpoint today, here is what will fail before the request even reaches your application code:
1. Web Application Firewalls (WAFs) will drop it (or ignore the body)
Most WAFs operate on explicit allowlists for HTTP methods (usually GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD).
If a WAF sees a method it doesn't recognize, it drops the connection. It doesn't return a 405 Method Not Allowed; it assumes it's a protocol smuggling attack and severs the TCP connection.
Worse, some WAFs might pass the request through but fail to inspect the body because they only scan POST or PUT payloads for SQL injection. That leaves your backend completely exposed to malicious payloads. Before you ship QUERY, you need to audit your WAF and any hardware load balancers to ensure they pass the verb through and actively inspect its body.
2. Framework routing engines will return 404
As of mid-2026, the underlying HTTP parsers in Node (which Express uses) and Python (which Django/FastAPI use) are still catching up.
Most framework routers maintain internal dictionaries mapping GET/POST to handler functions. When a QUERY request arrives, the router doesn't know where to put it. You will likely have to write custom middleware to intercept the raw request stream and manually route it, bypassing the framework's native decorators or route definitions.
3. Caching layers need explicit configuration (and introduce poisoning risks)
Just because the RFC says QUERY is cacheable doesn't mean Redis or Varnish will magically do it safely.
By default, Varnish and Nginx cache keys are built from $scheme$proxy_host$request_uri. If you send two QUERY requests to the same URL with different JSON bodies, a naive proxy will serve the same cached response for both, because it isn't hashing the body into the cache key.
This is a trivial path to cache poisoning. One user's complex search result gets cached and served to the next user.
To safely cache QUERY requests, you have to rewrite your cache configuration to buffer the request body, hash it, and append that hash to the cache key. Any middleware that tries to normalize the JSON or decode the body before hashing introduces a margin for error. Buffering request bodies in the cache layer also increases memory pressure and latency.
4. CSRF middleware blind spots
Cross-Site Request Forgery protections usually ignore GET requests because they cannot change state. QUERY is also marked as a safe method.
If your CSRF middleware only checks traditional state-changing methods like POST, PUT, and DELETE, a QUERY endpoint will bypass those checks completely. If a developer accidentally builds a QUERY endpoint that logs a search history to a database or updates a rate limit counter, you have an unauthenticated state change.
5. CORS preflight overhead
QUERY is not a CORS-safelisted method. Cross-origin browser clients will trigger a preflight OPTIONS request before sending the actual QUERY request. You have to account for that extra round trip in latency-sensitive applications, and your API gateway needs to handle those preflight requests correctly.
The migration trade-off
The inertia behind POST /search is massive. It works. The tooling understands it. The firewalls allow it.
Moving to QUERY gives you automatic retries and native caching. If your read endpoints are constantly timing out due to complex filters, and you can't cache them because they use POST, QUERY is exactly what you need.
But if you are going to refactor, you have to coordinate across the entire stack:
- Update frontend fetching libraries (which might not expose a
querymethod yet, forcing rawfetchcalls). - Reconfigure the WAF to allow the verb and inspect its body.
- Update the CDN cache key logic to hash request bodies securely.
- Patch your backend framework's router to handle the verb.
- Audit your CSRF middleware to ensure it covers edge cases.
IMO, for an existing high-traffic endpoint, the "POST works fine" argument is going to win every sprint planning meeting for the next two years.
Save QUERY for new greenfield services where you can configure the infra from scratch. For legacy systems, keep POSTing your searches until the ecosystem catches up.
Reference: RFC 10008: The HTTP QUERY Method
Top comments (0)