The HTTP QUERY method is designed for a familiar problem. Your search endpoint starts with a harmless-looking URL: GET /products?brand=Lenovo&max_price=1500. Then the filters grow. A client sends a long list of IDs, nested conditions, or a structured expression, and the URL stops being a comfortable place to put the query. You switch to POST, but now an intermediary cannot tell from the method alone whether it is safe to repeat.
HTTP QUERY is designed for this gap. Standardised in RFC 10008, QUERY carries a query description in request content while defining the operation as safe and idempotent. It gives APIs an explicit method for a body-based query, with carefully specified retry and caching semantics.
Why the HTTP QUERY method exists
GET is an excellent fit when the request can be expressed compactly in the target URI. A URL can be bookmarked, shared, logged, and used directly as the identifier of a selected resource. But the URI travels through multiple clients, proxies, gateways, and servers, each with its own practical request-target limit. There is no single maximum size that every system on the route promises to accept. RFC 10008 notes that HTTP recommends support for request URIs of at least 8,000 octets, while acknowledging that size limits in an uncoordinated request path are difficult to know in advance.
There is an important nuance behind the familiar claim that “GET cannot have a body.” HTTP messages can carry content with a GET request, but RFC 9110 gives GET content no generally defined semantics. A client should not send it unless it has a private arrangement with the origin server, and some implementations may reject it. The practical issue is interoperability, not the physical impossibility of transmitting bytes.
POST solves the body problem, and many APIs use it to submit complex searches. Yet POST is defined as resource-specific processing of the enclosed content. It may be used for a read-only search, but the method does not tell a generic client, cache, or intermediary that this particular POST is safe to repeat. That intent exists only in the API’s private contract.
GET, POST, and HTTP QUERY: what each one says
HTTP methods are part of the protocol’s meaning. They help clients and intermediaries understand what the sender is asking for, not just which server-side function to invoke. Here is the practical difference for a search operation:
| Method | Where query data goes | Safe by definition? | Idempotent by definition? | Can a response be reused? |
|---|---|---|---|---|
| GET | Usually the URI | Yes | Yes | Yes, subject to HTTP cache rules |
| POST | Request content | Not necessarily | Not necessarily | Only under specific rules, typically to satisfy later GET or HEAD requests |
| QUERY | Request content | Yes | Yes | Yes, for subsequent QUERY requests when the cache supports it |
The table describes the methods’ protocol semantics, not what every deployed server happens to implement. RFC 9110 says general-purpose servers must support GET and HEAD; other methods are optional. A service can therefore implement QUERY correctly while a gateway in front of it still rejects the request.
Send a structured query with HTTP QUERY
Here is a hypothetical product-search endpoint. The JSON shape is an API design choice, not a format mandated by RFC 10008. The standard defines the method semantics; the target resource and the request’s media type define what the body means.
QUERY /products HTTP/1.1
Host: shop.example
Content-Type: application/json
Accept: application/json
{
"category": "laptops",
"price": { "max": 1500 },
"brands": ["Lenovo", "Dell", "Apple"],
"inStock": true,
"sort": "-rating",
"pageSize": 25
}
A server might return 200 OK with the matching products as response content. A server receiving QUERY must reject the request if its Content-Type is missing or inconsistent with the body. The RFC also defines Accept-Query, a response header a resource can use to advertise the query media types it accepts. For example:
HTTP/1.1 200 OK
Accept-Query: "application/json"
Content-Type: application/json
That header gives a client a way to discover supported query formats, rather than guessing whether an endpoint accepts JSON, form data, SQL, or some other representation. It does not define the query language itself. RFC 10008, Sections 2 and 3
Safe and idempotent mean different things
“Safe” means the client is asking for an operation that does not change the state of the target resource. “Idempotent” means that making the same request more than once has the same intended effect on that resource as making it once. Safe methods are idempotent, but the terms answer different questions.
For a search, safety means the client is requesting results rather than asking the server to alter the product catalogue. Idempotency means that a retry after a dropped connection does not accidentally create a second order or apply a second update. The server may still record each request in logs, count usage, or create a separate result resource when the RFC permits it. Those incidental actions do not change the requested operation’s safe semantics.
This makes QUERY easier to retry automatically when a connection fails before the client receives a response. The client does not know whether the original response was lost before or after the server finished processing. With a method defined as idempotent, repeating an identical query is permitted by the HTTP semantics. This is not a guarantee that retries are free: an expensive query can still consume CPU, database capacity, or money, so clients should use sensible retry budgets and backoff.
Can the QUERY method really be cached?
Yes, the specification makes QUERY responses cacheable. A cache may use a stored response to satisfy a later QUERY request, provided normal freshness, validation, and reuse rules allow it. The essential detail is that the request body is part of the cache key, along with related metadata such as the content type. Two searches to the same path with different filters must not collide into one cache entry.
That makes caching QUERY more involved than caching a typical GET. A cache must understand the method and read enough of the request content to construct the correct key. A cache that only keys on method and URL, ignores bodies, or normalizes query JSON differently from the origin could return the wrong result. The RFC allows caches to normalize only semantically insignificant differences, and warns that incorrect normalization can cause false matches.
“Cacheable” is permission in the protocol, not a promise that every CDN, reverse proxy, framework, or browser cache will store QUERY responses today. HTTP caching rules already permit caching methods beyond GET when their specifications define the rules, but a cache must understand the method and the relevant caching behaviour. In practice, test each component in your request path and check its cache key, freshness, validation, and invalidation behaviour before relying on reuse. See RFC 9111, HTTP Caching, and RFC 10008, Section 2.7.
What the QUERY method does not solve
It does not make every query shareable as a link. The body is not part of the URI, so a plain QUERY request cannot be copied into a bookmark that contains the full query. RFC 10008 provides an option: the server can return a Location identifying an equivalent resource that a client can retrieve later with GET, or a Content-Location identifying the query result. Those are server choices, not automatic properties of every QUERY endpoint.
It does not define your search language. The application still needs to specify its schema, validation, limits, sort rules, pagination, authorization, and error responses. Treat the query body as untrusted input. Safe describes the method’s intended effect on server state; it does not mean harmless input, low cost, or exemption from authentication and rate limiting.
It does not hide sensitive data by itself. RFC 10008 notes that request URIs are more likely than request content to appear in logs, which can make QUERY useful when long or sensitive parameters should not be placed in a URI. But bodies can also be logged by applications, proxies, tracing systems, and security tools. Use HTTPS, review logging and retention policies, and avoid placing secrets in a search body unless your system is designed to protect them.
Browser and infrastructure support still matters
Browser code can request non-safelisted methods through APIs such as Fetch, but a cross-origin QUERY request triggers a CORS preflight. The server must permit the method in its CORS response, and the browser’s preflight request adds a round trip before the actual query. This is a protocol requirement, not evidence that QUERY cannot be used from a browser. Fetch Standard
Outside the browser, verify support across your complete path: client library, API framework, authentication middleware, reverse proxy, gateway, WAF, observability pipeline, and cache. HTTP servers are not generally required to implement every registered method. An unrecognized or unimplemented method is normally answered with 501 Not Implemented; a recognized method that the target does not allow is normally answered with 405 Method Not Allowed. RFC 9110, Section 9.1
If you are refining how endpoints express resource operations more broadly, see our guide to FastCRUD for FastAPI and API architecture.
Should you use the QUERY method now?
Consider QUERY for a new endpoint when the request describes a read-only operation, the query body is materially more useful than URI parameters, and explicit safe, repeatable semantics help clients or intermediaries. Keep GET when the query is compact and a shareable URI is valuable. Keep POST when it fits your operation or when the infrastructure you need does not yet support QUERY. There is no need to rewrite a working POST search just to adopt a new method.
And remember the headline needs a little context. QUERY was published as RFC 10008 in June 2026, roughly 16 years after PATCH (RFC 5789, March 2010). It is a new general-purpose HTTP method, while older registered methods such as WebDAV SEARCH already existed. So “HTTP’s first new method in 16 years” is a punchy shorthand, not a claim that no HTTP method of any kind was added during that period.
The important change is not merely that HTTP gained another verb. QUERY gives clients a standard way to say: “Here is a body describing a query; repeating it is safe, and a cache that understands the method can reuse its result.” That is a useful addition. Whether it is useful in your production API depends on support throughout the path from client to origin.