Why complex queries finally got their own HTTP method — and what that changes about API design For years, one deceptively simple question has kept coming up in API design: How should we represent a complex query? When the query is small, the answer seems obvious: GET /customers?status=ACTIVE&city=Goiania It is simple, readable, and aligned with HTTP semantics. But systems rarely stay simple forever. Soon you have multiple filters, date ranges, grouping, sorting, field selection, compound conditions, pagination, and nested criteria. That URI starts turning into something like this: GET /customers? status=ACTIVE,PENDING& states=GO,DF,MT& createdFrom=2025-01-01& createdTo=2026-09-01& nameContains=danilo& sortBy=createdAt& direction=DESC& page=1& size=50 And this is still a relatively simple example. At some point, many APIs make a pragmatic decision: POST /customers/search Content-Type: application/json { "filters": { "status": ["ACTIVE", "PENDING"], "states": ["GO", "DF", "MT"], "createdAt": { "from": "2025-01-01", "to": "2026-09-01" } }, "sort": [ { "field": "createdAt", "direction": "DESC" } ], "page": 1, "size": 50 } Technically, it works. The problem is that we are now using POST to represent an operation that is still, conceptually, just a query. For a long time, we simply lived with that semantic mismatch. Now HTTP has a specific answer for it. In June 2026, the IETF published RFC 10008 — The HTTP QUERY Method, a Standards Track document classified as a Proposed Standard. The new QUERY method was officially registered by IANA as both safe and idempotent. And perhaps the most interesting part is not the new method itself. It is understanding why it needed to exist in the first place. 1. The problem does not start with POST. It starts when GET stops being comfortable For simple queries, GET remains an excellent choice. GET /products?category=LAPTOP&available=true The URI clearly identifies what we want to retrieve. There is no reason to abandon that. RFC 10008 itself makes this point clear: small queries are still likely better expressed using GET. The problem begins when the query stops being a small set of parameters and starts behaving like a structured data model. Consider an analytics API: { "filters": { "period": { "start": "2026-01-01", "end": "2026-08-31" }, "branches": [10, 21, 32, 44], "statuses": ["INVOICED", "DELIVERED"], "customer": { "states": ["GO", "DF"], "segments": ["WHOLESALE", "DISTRIBUTOR"] } }, "groupBy": [ "branch", "month" ], "metrics": [ "revenue", "orderCount", "averageOrderValue" ], "sort": { "field": "revenue", "direction": "DESC" } } Can we serialize all of that into a URI? In many cases, yes. But “can we?” and “should we?” are two different questions. RFC 10008 points out several practical concerns: different components along the request path may enforce different URI length limits; some structures are inefficient or awkward to encode in a URI; URIs are more likely to appear in logs, browser history, and bookmarks; every distinct parameter combination effectively becomes a different URI. 2. The pragmatic solution we used for years: POST for search When query parameters start getting too large or too structured, a natural solution is to move the query into the request content. POST /orders/search Content-Type: application/json { "customers": [1024, 2048, 4096], "statuses": ["PAID", "PROCESSING"], "period": { "start": "2026-08-01", "end": "2026-08-31" } } The API immediately becomes easier to work with. Now we have: nested structures; arrays; compound filters; clearer typing; room for contract evolution; no massive query string. And using POST this way is not automatically a violation of HTTP. POST is intentionally broad. The target resource is expected to process the enclosed content according to its own semantics. So this: POST /orders/search can work perfectly well. The problem is somewhere else. If an intermediary sees only: POST /orders/search it cannot know that the operation was designed to be read-only. That knowledge lives inside the application contract. You need to understand that specific endpoint to know: “This POST does not modify state. It only executes a query.” And that is where the real semantic gap appears. 3. GET communicates the right intent. POST carries the payload we need We want two different properties. On one side: GET communicates retrieval semantics very well. On the other: POST naturally carries structured request content. The problem is that neither method precisely expressed: “I want to send a potentially complex query description, while keeping the operation safe and idempotent.” That is exactly the space QUERY is designed to fill. 4. So what exactly is QUERY? With QUERY, we can write: QUERY /customers HTTP/1.1 Content-Type: application/json Accept: application/json { "filters": { "statuses": ["ACTIVE", "PENDING"], "states": ["GO", "DF"] }, "sort": { "field": "createdAt", "direction": "DESC" }, "limit": 50 } The /customers resource defines the scope of the query. The request content defines how that resource should be queried. That difference may look small, but it matters. According to RFC 10008, QUERY asks the target resource to execute a query operation within its own scope. The request content and its media type participate in defining that query. A useful mental model is: /customers ↓ defines where to query request content ↓ defines what to query That also explains why: QUERY /customers and: QUERY /orders may accept completely different query languages. The meaning of the request content belongs to the contract of the target resource. 5. QUERY is not simply “GET with a body” This distinction matters. It is tempting to describe QUERY as: “GET with a body.” But that is not an accurate representation of the specification. RFC 9110 states that content received in a GET request has no generally defined semantics. Clients also should not send content in GET unless there is prior agreement that the server and intermediaries will handle it correctly. So this: GET /customers Content-Type: application/json { "state": "GO" } does not suddenly acquire universal query semantics just because JSON was included in the request. With QUERY, the situation is different. QUERY /customers Content-Type: application/json { "state": "GO" } The request content exists specifically to describe the query being executed. So the difference is not merely mechanical. It is semantic. GET → transfer a representation of the target resource QUERY → execute this query within the scope of the target resource RFC 10008 explicitly defines that distinction. 6. Safe: the query should not request a state change To understand why QUERY matters, we need to revisit two fundamental HTTP properties. The first is safety. A method is considered safe when its semantics are essentially read-only: the client is not requesting or expecting a state change as the purpose of the operation. That does not mean the server performs absolutely no side effects. It may still: write logs; record metrics; update telemetry; feed audit systems. All of that may happen during QUERY, just as it may happen during GET. The important distinction is this: those side effects are not what the client asked for. So this makes sense: QUERY /orders { "status": "OVERDUE" } This does not: QUERY /orders { "action": "CANCEL", "status": "OVERDUE" } If the intent is to change the state of the orders, the operation is no longer safe. Calling something QUERY does not magically turn a mutation into a query. The semantics of the operation must match the semantics of the method. 7. Idempotent: retrying the query should not change the intended effect The second property is idempotency. A method is idempotent when multiple identical requests have the same intended effect on the server as a single request. Because QUERY is safe, it is also defined as idempotent. That matters operationally. Imagine this sequence: Client | | QUERY /customers v Server | | response X connection fails The client does not know whether the server completed the request. Because the operation is idempotent, it can be retried: Client | | QUERY again v Server without the risk of accidentally repeating an intended state-changing operation. RFC 10008 explicitly highlights retries as one of the consequences of this property. 8. GET, QUERY, and POST side by side At this point, we can compare the three methods more precisely. Characteristic GET QUERY POST Safe Yes Yes Not necessarily Idempotent Yes Yes Not necessarily Request content No generally defined semantics Expected Expected Simple queries Excellent Possible, usually unnecessary Possible Complex queries Can become awkward Natural use case Commonly used Cacheable responses Yes Yes Yes, under specific conditions Automatic retry based on method semantics Natural Natural Cannot be assumed generically URI representing the query The URI itself Optional Not inherent to the method The caching row deserves special attention. Saying: “POST cannot be cached, while QUERY can” would be incorrect. RFC 9110 allows responses to POST to be cached when specific requirements are met. However, a cached POST response cannot generally be reused to satisfy another POST, because the method is potentially unsafe. Under specific conditions, it may later satisfy GET or HEAD. RFC 10008, on the other hand, explicitly defines how a cached QUERY response may be reused for future QUERY requests. This is a good example of why semantics matter to infrastructure, not just to API readability. 9. The query content is part of the contract There is another subtle point in the RFC. When request content is present in a QUERY, the Content-Type matters. The server must reject the request when the media type information is missing or inconsistent with the content being sent. For example: QUERY /customers Content-Type: application/json { "state": "GO", "status": "ACTIVE" } Our API could define application/json as a custom query DSL. But there is an important nuance: JSON defines the data representation. It does not define the query language by itself. This: { "state": "GO" } only means “filter customers in Goiás” because our API contract gave it that meaning. In a more formal API, we could even define a dedicated media type: Content-Type: application/vnd.company.query+json That makes both format and semantics more explicit. RFC 10008 also defines coherent error behavior: missing or invalid media type information may lead to 400 Bad Request; an unsupported media type may lead to 415 Unsupported Media Type; syntactically valid content that cannot be processed may lead to 422 Unprocessable Content; an unavailable response representation requested by the client may lead to 406 Not Acceptable. And that brings us to another new piece introduced by the RFC. 10. Accept-Query: the server can tell clients how it accepts queries RFC 10008 also defines the header: Accept-Query It allows a resource to advertise which query formats it supports. We can discover supported methods: OPTIONS /customers HTTP/1.1 Response: HTTP/1.1 200 OK Allow: GET, QUERY, OPTIONS, HEAD Now we know that the resource supports QUERY. We can also discover supported query formats. HEAD /customers HTTP/1.1 Response: HTTP/1.1 200 OK Accept-Query: "application/vnd.company.query+json" RFC 10008 presents HEAD as one possible way to discover supported query formats. A useful distinction is: Allow ↓ Which methods can I use? Accept-Query ↓ Which query formats can I send? The RFC also uses formats such as application/sql and JSONPath in examples. That demonstrates the flexibility of the protocol. It does not mean exposing raw SQL through a public API is automatically a good idea. Allowing arbitrary SQL can increase coupling to the persistence layer and create serious challenges around security, authorization, isolation, and query cost. The protocol gives us the capability. Good API design is still our responsibility. 11. Caching becomes more powerful — and more complicated Now we get to one of the most technically interesting parts of QUERY. Consider these two requests: QUERY /customers Content-Type: application/json { "status": "ACTIVE" } and: QUERY /customers Content-Type: application/json { "status": "BLOCKED" } The method is the same. The URI is also the same. But the queries are different. So a cache cannot build its cache key from only: method + URI RFC 10008 requires the cache key for QUERY to incorporate the request content and related metadata. Conceptually: QUERY + /customers + query content + relevant metadata ↓ cache key 12. The query can get its own URI Imagine: QUERY /customers Content-Type: application/json { "status": "ACTIVE", "state": "GO" } The server processes the query and responds: HTTP/1.1 200 OK Content-Type: application/json Location: /queries/customers/8f3a At that point, the server is effectively saying: There is an equivalent resource representing this query. Later, the client may simply request: GET /queries/customers/8f3a without resending the full query content. RFC 10008 refers to this idea as an equivalent resource. The flow looks like this: QUERY /customers + complex query ↓ server ↓ Location: /queries/customers/8f3a ↓ GET /queries/customers/8f3a 13. Location and Content-Location do not mean the same thing Suppose the query is: All active customers in Goiás. The server could respond: HTTP/1.1 200 OK Location: /queries/customers/8f3a Content-Location: /results/customers/91ac Those URIs may represent different things. Location Represents the equivalent resource for the query itself. “active customers in Goiás” If the underlying data changes and I access that resource later, I may get different results. Content-Location May identify the resource corresponding to the result of that specific execution. “the set of customers returned when I ran this query” RFC 10008 explicitly defines both mechanisms. A simple way to remember it: Location → how to repeat the query Content-Location → where to find that result This distinction becomes even more interesting when caching and conditional requests enter the picture. 14. ETag and conditional requests still fit naturally Suppose the server created: Location: /queries/customers/8f3a The client requests: GET /queries/customers/8f3a and receives: HTTP/1.1 200 OK ETag: "customers-go-42" Later: GET /queries/customers/8f3a If-None-Match: "customers-go-42" If nothing relevant changed: HTTP/1.1 304 Not Modified RFC 10008 also allows conditional QUERY requests and integrates with existing HTTP validators. That gives us an elegant composition: complex query ↓ QUERY ↓ equivalent URI ↓ GET ↓ ETag / Last-Modified ↓ 304 when appropriate The new method does not try to replace existing HTTP mechanisms. It fits into them. That is one of the most interesting aspects of the RFC design. 15. What about pagination? QUERY does not eliminate pagination. A query may still return millions of records. Moving the criteria into the request content does not change that. For example: QUERY /orders Content-Type: application/json { "filters": { "status": "INVOICED" }, "pagination": { "limit": 100, "cursor": "eyJ1bHRpbW9JZCI6MTIzNDU2fQ" } } RFC 10008 notes that while HTTP Range Request semantics may be applicable to QUERY, query languages often already have their own mechanisms for limiting or paginating results, and those mechanisms are usually more appropriate. So: QUERY ≠ pagination solution QUERY solves how to semantically express a structured query. Pagination remains a separate API design concern. 16. There is also a privacy benefit — but do not confuse it with security Consider: GET /customers?ssn=123456789&email=user@example.com URIs are more likely to appear in: logs; observability tools; browser history; proxies; bookmarks; intermediary systems. Moving data out of the URI and into request content can reduce some forms of accidental exposure. RFC 10008 explicitly mentions this motivation. But be careful. That does not mean the contents of a QUERY request are secret. They may still appear in: application logs; traces; APM tools; debugging systems; gateways; WAFs; audit platforms. And, of course, TLS is still required when transmitting sensitive information over the public Internet. So: request body ≠ automatically protected data The more accurate conclusion is: Sensitive information is often inappropriate in a URI, and QUERY gives us a way to express complex queries without requiring that information to appear there. In addition, if a server creates a URI for a query that contained sensitive information, RFC 10008 recommends that the generated URI should not expose that information again. 17. What about browsers? CORS still applies This is one of the practical limitations to keep in mind. QUERY is not currently part of the CORS-safelisted methods. So a cross-origin browser request using QUERY will require a preflight request. Conceptually: Browser | | OPTIONS v Server | | CORS allowed v Browser | | QUERY v Server That does not prevent the use of QUERY. But web applications need to account for: CORS configuration; gateways; proxies; WAFs; API gateways; service meshes; HTTP client libraries; observability; corporate security policies. And that highlights an important distinction between: “There is an RFC.” and: “I can roll this out in production tomorrow without checking my infrastructure.” Those are very different statements. 18. A new method does not mean instant ecosystem support HTTP was designed to be extensible. RFC 9110 even instructs intermediaries to forward unrecognized elements whenever possible. But real systems depend on real implementations. A production request path may look like this: client ↓ CDN ↓ WAF ↓ API Gateway ↓ Load Balancer ↓ Reverse Proxy ↓ framework ↓ application If just one component has a hard-coded list such as: GET POST PUT PATCH DELETE QUERY may stop there. Before adopting it, I would validate at least: HTTP clients; browsers, when applicable; CDNs; WAFs; API gateways; reverse proxies; load balancers; frameworks; OpenAPI tooling; observability platforms; CORS policies; caching infrastructure. This concern also appears in Spring Framework implementation discussions, particularly around caching, conditional requests, and intermediary support. Standardization is the beginning of adoption. Not the end. 19. What about Java? We can already send QUERY The standard Java HTTP client has an interesting advantage here. HttpRequest.Builder allows applications to provide an arbitrary HTTP method name through: method(String, BodyPublisher) So we do not have to wait for the API to expose a dedicated .QUERY() method. For example: import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; /** * Author: Danilo Fernando * Date: September 10, 2026 * * Demonstrates how to send a query using the HTTP QUERY method * defined by RFC 10008. */ public final class CustomerQueryHttp { private static final URI ENDPOINT = URI.create("https://api.example.com/customers"); private CustomerQueryHttp() { // Prevents instantiation of this utility class. } public static HttpResponse<String> query() throws Exception { final var body = """ { "filters": { "status": "ACTIVE", "state": "GO" }, "limit": 50 } """; final var request = HttpRequest.newBuilder() .uri(ENDPOINT) .header("Content-Type", "application/json") .header("Accept", "application/json") .method( "QUERY", HttpRequest.BodyPublishers.ofString(body) ) .build(); try (final var client = HttpClient.newHttpClient()) { return client.send( request, HttpResponse.BodyHandlers.ofString() ); } } } The important part is here: .method( "QUERY", HttpRequest.BodyPublishers.ofString(body) ) Java already allows us to define the method and request content explicitly. But being able to construct the request does not mean every component between the client and server will accept it. Again: protocol, library, and infrastructure support all need to line up. 20. What about Spring? The story is unfolding right now This is particularly interesting because RFC 10008 was published only recently. In the current stable Spring Framework 7.0.x line, RequestMethod still reflects the traditional methods. However, basic HTTP QUERY support has already been implemented in Spring Framework and was merged on August 20, 2026, targeting the 7.1.0-M2 milestone. The implementation covers important pieces such as: recognition of the new method; support in HttpMethod, HttpHeaders, and RequestMethod; request body handling; Accept-Query integration; OPTIONS-related behavior; parts of the HTTP client infrastructure. Interestingly, the Spring team chose not to immediately introduce abstractions such as @QueryMapping or @QueryExchange. That decision is significant. The RFC is new, and the ecosystem still needs time to show how the method will actually be used before the framework expands its public API surface. That kind of restraint is a useful engineering lesson. A specification may be brand new. We do not need to create an abstraction for every possibility before seeing how the industry adopts it. Once the corresponding support is available in the Spring version being used, a controller could look something like this: @RestController @RequestMapping("/customers") public class CustomerController { /** * Author: Danilo Fernando * Date: September 10, 2026 * * Executes a structured customer query without modifying * the state of the queried resource. */ @RequestMapping( method = RequestMethod.QUERY, consumes = MediaType.APPLICATION_JSON_VALUE, produces = MediaType.APPLICATION_JSON_VALUE ) public List<CustomerResponse> query( @RequestBody final CustomerQueryRequest query ) { return List.of(); } } At the time of writing, however, this support belongs to the upcoming 7.1 line and should not be confused with availability in the current stable 7.0.x line. That distinction matters. 21. Should we migrate all our GET endpoints to QUERY? No. Definitely not. Consider: GET /customers/123 There is no meaningful benefit in changing that to: QUERY /customers/123 Another example: GET /customers?state=GO It is still simple, readable, addressable, and extremely well understood across the HTTP ecosystem. RFC 10008 explicitly notes that small queries are still likely better served by GET. A practical rule of thumb might look like this. Use GET when the query maps naturally to a URI; the filters are relatively simple; having an addressable URI is valuable; sharing and bookmarking are useful; traditional caching behavior is desirable; the query does not expose data that should not appear in a URI. Consider QUERY when the operation is fundamentally read-only; it should be semantically safe; it should be semantically idempotent; the query structure is complex; serializing it into a URI is awkward; request content is the natural representation of the query; your infrastructure supports the method; explicit HTTP semantics and retry behavior add value. Keep considering POST when the operation is not safe; processing may intentionally change state; the ecosystem you depend on does not yet support QUERY; immediate compatibility matters more than semantic precision; you already have a stable API where migration would not deliver enough value. The existence of a new method does not make old designs automatically wrong. It gives us a semantically better option for a specific class of problems. 22. No, POST /search did not suddenly become “wrong” This deserves its own section. Imagine a mature API exposing: POST /orders/search to thousands of consumers. RFC 10008 does not suddenly mean: “You need to migrate immediately.” Any contract change has to be evaluated in terms of cost and benefit. You may need to update: SDKs; gateways; mocks; tests; clients; documentation; security rules; observability; infrastructure; external contracts. Migrating only so you can say: “We use the new HTTP method” would be a weak justification. A more responsible strategy would be: consider QUERY first for new APIs where it is a natural fit; validate infrastructure support; watch adoption across major libraries and gateways; measure real benefits; migrate existing APIs only when there is meaningful value. The HTTP method is part of the contract. Contracts should not change just because a new technology is exciting. 23. QUERY does not eliminate the need to design a good query language There is another risk. Now that we can send structured content, someone may think: “Great. I can put anything in there.” Not quite. QUERY solves the semantics of the HTTP interaction. It does not design our DSL for us. We still need to decide: which filters are supported; how filters can be combined; how sorting works; how fields can be selected; how pagination works; which limits apply; how nesting depth is controlled; how expensive queries are prevented; how authorization affects results; how the query language evolves; how semantically equivalent queries are normalized. For example: { "filters": { "and": [ { "field": "status", "operator": "EQUALS", "value": "ACTIVE" }, { "or": [ { "field": "state", "operator": "EQUALS", "value": "GO" }, { "field": "state", "operator": "EQUALS", "value": "DF" } ] } ] } } This might be a very good DSL. Or it might slowly turn into our own poorly designed version of SQL. That problem is still ours to solve. The RFC standardizes how query intent is carried over HTTP. It does not design the query model for us. 24. So what actually changed in API design? Now we can return to the original problem. Before, we often had: simple query ↓ GET complex query ↓ POST Now there is a third option: simple query ↓ GET complex query read-only safe idempotent ↓ QUERY command / processing potentially state-changing ↓ POST 25. The most important part is not the new method It is easy to look at RFC 10008 and summarize the entire story like this: “HTTP now has a QUERY method.” But that misses the most interesting part. HTTP is not merely a transport mechanism for sending JSON. If it were, we could simply write: POST /doEverything and encode every bit of intent inside the request payload. Methods, status codes, headers, validators, and resources exist so that important parts of the interaction can be understood without private knowledge of every individual application. That idea is deeply connected to the uniform interface constraint that helped shape the architecture of the Web. Fielding emphasized generality of interfaces, component independence, and the role of intermediaries as important architectural properties of REST. QUERY follows that direction. Instead of sending: POST and expecting every component to somehow know that, for this specific endpoint, POST means: “Run a read-only, safe, repeatable query.” we can finally say: QUERY and make that intent explicit in the protocol itself. That is the real contribution of RFC 10008. Conclusion QUERY was not created to replace GET. And it did not make POST /search invalid. It exists because HTTP had a legitimate semantic gap: queries that are too large or too structured to be conveniently represented in a URI, while still remaining safe and idempotent operations. With QUERY, we can now combine: structured request content; explicitly safe semantics; idempotency; retry behavior aligned with method semantics; defined query caching; conditional requests; discovery through Accept-Query; the ability to turn a query into a resource that can later be retrieved with GET. But the existence of an RFC does not eliminate adoption challenges. Frameworks, browsers, proxies, gateways, CDNs, WAFs, documentation tools, and caching layers still need time to mature their support. So the right decision is not: “QUERY exists. Let's use it.” A better question is: “Is this operation truly a safe, idempotent query? Is it complex enough to justify request content? And can our entire infrastructure preserve those semantics?” If the answer is yes, we finally have an HTTP method designed specifically for that scenario. And perhaps that is the most important part of the story: HTTP did not just get another method. It got a more precise way to communicate intent. References RESCHKE, Julian; SNELL, James M.; BISHOP, Mike. The HTTP QUERY Method. RFC 10008. Internet Engineering Task Force, June 2026. RFC Editor. Accessed: September 10, 2026. FIELDING, Roy; NOTTINGHAM, Mark; RESCHKE, Julian. HTTP Semantics. RFC 9110. Internet Engineering Task Force, June 2022. RFC Editor. Accessed: September 10, 2026. FIELDING, Roy; NOTTINGHAM, Mark; RESCHKE, Julian. HTTP Caching. RFC 9111. Internet Engineering Task Force, June 2022. RFC Editor. Accessed: September 10, 2026. INTERNET ASSIGNED NUMBERS AUTHORITY. Hypertext Transfer Protocol (HTTP) Method Registry. IANA, 2026. Accessed: September 10, 2026. FIELDING, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. 2000. PhD dissertation, University of California, Irvine, 2000. ORACLE. HttpRequest.Builder — Java SE 21 & JDK 21. Java Platform Documentation. Accessed: September 10, 2026. SPRING PROJECTS. Add RFC 10008 (QUERY HTTP method) support. Spring Framework, 2026. Accessed: September 10, 2026. WHATWG. Fetch Standard. Living Standard. Accessed: September 10, 2026.