FAQ — Common questions about HTTP QUERY
The questions that keep coming up on Reddit, Hacker News, and X — answered straight from RFC 10008.
Does QUERY replace GET?
Section titled “Does QUERY replace GET?”No. QUERY complements GET. When your query fits in the URL (under ~8000 octets), GET remains the best choice — simple, universal, cacheable with no extra effort. QUERY exists for when the query payload is too large, too sensitive to leak in logs, or too complex to serialize into a query string. The RFC is explicit: QUERY is an additional method, not a replacement (RFC 10008, Section 1).
Can I use QUERY in production today?
Section titled “Can I use QUERY in production today?”With caveats. Node.js 22+ accepts QUERY natively, Fastify supports it via addHttpMethod, and .NET 11 Preview already maps the method. The real risk is intermediaries: proxies, WAFs, and CDNs that don’t recognize the method may reject it or mishandle it. For internal APIs where you control the infrastructure, go ahead. For public APIs, keep a POST fallback for now.
Does GraphQL need the QUERY method?
Section titled “Does GraphQL need the QUERY method?”QUERY solves the classic “GET vs POST for GraphQL” debate. Today, GraphQL uses GET for cacheable queries (stuffed into the URL) and POST for mutations — but complex queries blow past URL limits. With QUERY, you send the body (the GraphQL query) with explicitly safe, idempotent semantics, and caches can operate normally. It’s exactly what was missing.
How does caching work for QUERY?
Section titled “How does caching work for QUERY?”The response is cacheable, but the cache key must include the request body (RFC 10008, Section 2.7). Caches may normalize the body — strip encoding, sort JSON fields — to avoid unnecessary misses. The server can return Content-Location (a URI for the result) and Location (a URI that re-runs the query via GET), enabling conventional caching after the first request.
How long until universal adoption?
Section titled “How long until universal adoption?”Community consensus points to 5–10 years for ubiquity. The RFC was published in June 2026. Node.js already supports it, OpenAPI 3.2 documents it, but CDNs, browsers (mandatory preflight), and legacy frameworks need time to catch up. For context: PATCH (RFC 5789) was published in 2010 and took years to become a framework default. Use QUERY today where it makes sense, but don’t expect universal support tomorrow.
Why wasn’t it named SEARCH?
Section titled “Why wasn’t it named SEARCH?”The original draft (2015–2021) was called SEARCH. The rename happened in November 2021. Reasons: SEARCH already existed in the IANA registry with WebDAV semantics (RFC 5323), required XML as its format, and carried historical WebDAV baggage “about which many have mixed feelings” (RFC 10008, Appendix B). QUERY is a clean name that reflects the relationship with the URI’s query component.
Is the request body required?
Section titled “Is the request body required?”Not technically, but without a body QUERY is semantically identical to GET — there’s no point. The RFC requires Content-Type to be present and consistent with the content; servers MUST reject requests without it (RFC 10008, Section 2). In practice: if you have no body, use GET.
Does it work with HTTP/1.1, HTTP/2, and HTTP/3?
Section titled “Does it work with HTTP/1.1, HTTP/2, and HTTP/3?”Yes, all of them. QUERY is defined at the HTTP semantic layer (RFC 9110), not the transport layer. It works over any protocol version the same way GET, POST, or any other method does. No version restrictions.
What if a proxy doesn’t recognize QUERY?
Section titled “What if a proxy doesn’t recognize QUERY?”RFC 9110 states that proxies SHOULD forward unknown methods (Section 9.1). A proxy may reject with 501, but the correct behavior is transparent forwarding. The practical risk: aggressive proxies/WAFs (corporate, legacy CDNs) that maintain closed method allowlists. Test before trusting intermediaries you don’t control.
Does OpenAPI support QUERY?
Section titled “Does OpenAPI support QUERY?”OpenAPI 3.2.0 (September 2025) added first-class support for QUERY operations. You can document QUERY endpoints in OpenAPI 3.2+ specs normally, and code generation tools are starting to emit clients with method support. Swagger UI and other visual tools are in the process of updating.
Does QUERY trigger a CORS preflight in browsers?
Section titled “Does QUERY trigger a CORS preflight in browsers?”Yes, always. QUERY is not in the CORS-safelisted methods list (GET, HEAD, POST). Every cross-origin QUERY request triggers an OPTIONS preflight. The RFC confirms this explicitly in Section 4 (Security Considerations). If preflight latency is a concern, consider same-origin requests or a reverse proxy.
Is QUERY safe for automatic retries?
Section titled “Is QUERY safe for automatic retries?”Yes. By definition, QUERY is safe (does not alter state) and idempotent (repeating produces the same result). Clients, proxies, and load balancers can retry automatically with no risk of side effects — unlike POST, where retries can duplicate operations. This is the primary practical gain over POST /search.