HTTP has a new standardized method called QUERY, defined in RFC 10008. It does not replace GET. Instead, it solves a long-standing API design problem: how to express a read-only query that needs a request body without misusing POST.
For years, developers have had to choose between imperfect options. GET is the natural method for retrieval, but it is limited by URL length, encoding complexity, and the lack of a request body in normal HTTP semantics. POST can carry a body, but it is not a semantic fit for safe, idempotent read operations. QUERY gives API designers a cleaner alternative.
Why HTTP needed QUERY
Modern APIs rarely deal with simple key-value lookups anymore. Search endpoints often need nested filters, arrays, pagination, sorting, date ranges, and structured conditions that become awkward or unreadable when forced into a URL. That is where teams have traditionally used POST for search, even when no data is being created or changed.
The problem is not that POST cannot work. The problem is that it sends the wrong signal about intent. HTTP semantics matter because they influence retries, caching behavior, intermediaries, developer expectations, and long-term maintainability. QUERY exists to align those semantics with what many “search” and “filter” endpoints are already doing in practice.
What QUERY means
RFC 10008 defines QUERY as a method that asks the target resource to process enclosed content and return the result in a safe and idempotent manner. In plain terms, the client is asking for data, not causing a state change, and repeating the same request should not create side effects.
That makes QUERY different from POST and closer in intent to GET. But it is not just a duplicate of GET with a body attached. It is a distinct method for query-style operations where the request content belongs in the body rather than the URI.
GET, POST, and QUERY
The easiest way to think about the three methods is this:
- GET retrieves a representation of a resource and is best for simple, URI-based requests.
- POST is broader and is commonly used when the request changes state, triggers processing, or performs actions that are not purely read-only.
- QUERY is for safe, idempotent request-body-based queries, especially when the input is too complex for a URL.
This is why QUERY matters to API design. It removes the need to overload POST just because GET is too constrained for a complex query payload.
Real-world use cases
QUERY is especially useful in systems where search criteria can get large or structured. That includes product catalogs, log search, analytics filters, document search, enterprise data platforms, and APIs that accept JSON-based query objects.
A typical example might look like this:
QUERY /products
Content-Type: application/json
{
"brands": ["Apple", "Dell"],
"minPrice": 50000,
"maxPrice": 150000,
"sortBy": "price",
"inStock": true
}
In that scenario, the request is clearly read-only, but the payload is far more expressive than a long query string. QUERY is designed for exactly that kind of API.
Why API teams should care
One of the biggest benefits of QUERY is semantic clarity. Developers, reviewers, and tooling can better understand that the operation is intended to fetch data rather than mutate state. That matters in large systems where API contracts have to be reliable and obvious to many teams.
It may also improve operational behavior over time. Because QUERY is defined as safe and idempotent, clients and intermediaries can reason about retries more confidently than they can with POST-based search endpoints. That does not automatically solve caching or infrastructure support across the ecosystem, but it creates a standard foundation for those conversations.
Important caveats
QUERY is new, so adoption will take time. Framework support, proxy behavior, API gateways, documentation tools, and developer familiarity will all need to catch up before it feels as common as GET or POST.
That means teams should not rush to change every search endpoint overnight. A practical approach is to use QUERY where it genuinely improves API semantics, while continuing to support established patterns where compatibility matters more than novelty.
What this changes
QUERY does not eliminate GET. GET is still the right method for standard resource retrieval and simple query strings. What QUERY changes is the design space for read-only operations that need structured input and cannot fit comfortably into a URL.
In other words, the web did not replace one method with another. It added a better tool for a very specific problem that has existed for a long time.
A practical rule of thumb
Use this simple decision model:
- Use GET when the request is a straightforward retrieval and the parameters fit naturally in the URI.
- Use QUERY when the operation is read-only but needs a request body for complex filters or search criteria.
- Use POST when the request changes state, starts a workflow, or performs a non-read-only operation.
That is the clearest way to explain QUERY without overselling it. It is not a universal replacement; it is a better semantic fit for a real and common API design problem.
References
- RFC 10008 — The HTTP QUERY Method: https://datatracker.ietf.org/doc/rfc10008/[datatracker.ietf]
- RFC Editor entry for RFC 10008: https://www.rfc-editor.org/info/rfc10008/[rfc-editor]
- MDN GET method reference: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods/GET[developer.mozilla]
Hashtags
#HTTP #QUERY #RFC10008 #APIDesign #RESTAPI #WebDevelopment #BackendEngineering #SoftwareEngineering #APISemantics #TechNews