HTTP QUERY Explained: Safe Requests That Include a Body

funkysi1701@gmail.com (funkysi1701) — Tue, 14 Jul 2026 07:30:00 +0000

For years, API designers have had an awkward choice when a search got too complex for a URL. Stuff it into a GET query string and hit practical URI length limits, or send a body with POST and pretend a read-only filter is a write. Neither option felt right.

In June 2026 the IETF published RFC 10008 , which defines QUERY — a new HTTP method that is safe and idempotent like GET, but carries request content like POST. That long-standing gap finally has a standard answer.

The problem QUERY solves

GET is the right semantic for “please return something, and I am not asking you to change state.” It is safe, idempotent, and cacheable. The catch is where the input lives: in the URI. Complex filters, GraphQL-style documents, Elasticsearch queries, or large multi-field search payloads do not always fit comfortably in a URL. RFC 9110 suggests supporting request targets of at least 8,000 octets, but browsers, proxies, and gateways vary — and overflowing those limits is a practical failure, not a theoretical one.

URI length is not the only issue. Request URIs — including query-string filters — are far more likely to appear in access logs, browser history, and bookmarks than request bodies. If your search payload contains personal data or other sensitive filters (think GDPR and PII), stuffing it into a GET URL is often a compliance headache. That is one reason many teams already use POST /search: the body is less exposed in everyday logging.

POST accepts a body with a clear media type, which is perfect for structured input. The catch is what the rest of the HTTP stack is allowed to assume. HTTP treats POST as potentially unsafe and non-idempotent: a particular search endpoint can be a pure read in practice, but intermediaries cannot tell that from the method alone. They cannot safely auto-retry a failed POST the way they can a GET, and shared caches cannot treat it as a normal repeatable read. Tooling that assumes “POST means mutate” often groups a catalogue search with create/update traffic — culturally understandable, even when your handler never writes.

People sometimes tried GET with a body. RFC 9110 is blunt about that: content on a GET has no generally defined semantics, must not change the meaning of the request, and some implementations reject it because of request-smuggling concerns. That was never the answer.

QUERY is the method that says what we meant all along: process this enclosed content as a query, safely and idempotently, and return the result.

What RFC 10008 actually defines

From the abstract:

A QUERY requests that the request target process the enclosed content in a safe and idempotent manner and then respond with the result of that processing.

Compared with GET, you are not asking for a representation of the target URI by itself. You are asking the target resource to run a query within its scope, using the request body and Content-Type to define that query. Servers must fail the request if Content-Type is missing or inconsistent with the content.

Key properties:

Property	Meaning for QUERY
Safe	The client does not request or expect a state change on the target resource
Idempotent	The same request can be retried after a connection failure
Cacheable	Successful responses may be stored and reused for subsequent QUERY requests
Body required for the query	The query lives in the content, not forced into the URI

Safe here is the HTTP meaning: the client is not asking to change the target resource (for example /api/products). That does not ban every side effect on the planet. Your server can still increment metrics, write an audit row, or — as the RFC allows — create temporary resources behind Location / Content-Location so results can be fetched again with GET. What intermediaries can assume is that QUERY is a read against the resource you addressed, not a create or update of it.

Idempotent means repeating the same request does not cause additional side effects beyond what a single successful attempt would cause. If the connection drops after you send a QUERY, a client or proxy can send it again without worrying that the second attempt will “do something twice” — unlike a non-idempotent POST that might create two orders if retried. It does not mean the response is frozen forever, and it is not the same as “cache forever.” Like GET, two identical QUERY calls can return different results if the underlying catalogue changed between them.

A 200 OK means the query was processed successfully and the results are in the response content. That matches how people already think about search endpoints — now with HTTP semantics that intermediaries can trust.

How it compares to GET and POST

	GET	QUERY	POST (as a “search”)
Request body for the query	No (undefined)	Yes	Yes
Safe (assumed by intermediaries)	Yes	Yes	Not assumed
Idempotent (assumed by intermediaries)	Yes	Yes	Not assumed
Typically cacheable as a read	Yes	Yes	Not assumed
Fits large / structured input	Poorly (URI limits)	Yes	Yes
Keeps filters out of the URI (logs / bookmarks)	No	Yes	Yes
Auto-retry after failure	Safe	Safe	Risky

You still use GET when the URI alone identifies what you want — and when you are comfortable with that URI being logged. You still use POST when you are creating or changing something, or when you need a body today and cannot yet rely on QUERY end to end. QUERY is for the awkward middle: read-only operations whose input belongs in a body, with semantics intermediaries can trust.

Caching, Location, and Accept-Query

Caching QUERY is a bit more work than caching GET, because the cache key must incorporate the request content (and related metadata). Some caches may normalise insignificant differences when building that key; clients that care can send Cache-Control: no-transform as advisory guidance.

The RFC also gives servers a way to hand clients a simpler follow-up:

Content-Location — a URI for a resource that holds the results of this query (temporary storage of what you just got).
Location — a URI for an equivalent resource that repeats the same query via GET, without resending the body.

That last point matters for CDNs and clients that are still catching up: after the first QUERY, subsequent hits can become ordinary GETs against a stored-query URI.

Discovery uses the new Accept-Query response field. A resource can advertise which query media types it understands, for example:

Accept-Query: application/json, application/sql

If you send an unsupported type, expect 415 Unsupported Media Type, and you may use Accept-Query (or Accept on error responses) to learn what to try next.

CORS and security notes

QUERY is not a CORS-safelisted method. Browser fetch calls will trigger a preflight OPTIONS check, the same way PUT or DELETE do. That is intentional: you do not want a body-carrying cross-origin method sliding past CORS just because it is “read-like.”

Putting filters in the QUERY body already helps versus a fat GET query string — less sensitive material in URIs that get logged or bookmarked. That benefit disappears if you then mint temporary Location or Content-Location URIs that echo those filters into the path or query. The RFC warns those URIs should not include sensitive portions of the original request content.

Using QUERY with ASP.NET Core

You do not need to wait for .NET 11 to try QUERY on the server. ASP.NET Core routing already accepts arbitrary method strings via MapMethods, and recent releases expose HttpMethods.Query (with HttpMethods.IsQuery) so you do not have to sprinkle the literal "QUERY" everywhere:

app.MapMethods("/api/products/search", [HttpMethods.Query], (ProductSearchRequest request) =>
{
 var results = ProductCatalogue.Search(request);
 return TypedResults.Ok(results);
});

A thin helper keeps call sites readable:

public static class HttpQueryExtensions
{
 public static IEndpointConventionBuilder MapQuery(
 this IEndpointRouteBuilder endpoints,
 string pattern,
 Delegate handler) =>
 endpoints.MapMethods(pattern, [HttpMethods.Query], handler);
}

What landed later is OpenAPI documentation. QUERY became a first-class Path Item operation in OpenAPI 3.2. In .NET 11, ASP.NET Core’s document generator recognises QUERY when you opt into that version — so Swagger / client generators see a proper query operation instead of an oddball method string:

builder.Services.AddOpenApi(options =>
{
 options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_2;
});

With OpenAPI 3.2, the operation appears as a sibling of get / post. On older document versions, generators may fall back to an extension such as x-oai-additionalOperations so the endpoint is not silently dropped. Until you are on that stack, you can still ship QUERY endpoints and document them by hand if needed.

Clients can call it with curl once the server understands the verb:

curl -X QUERY https://api.example.com/api/products/search \
 -H "Content-Type: application/json" \
 -d '{"category":"laptops","minPrice":500,"tags":["ultrabook","16gb"]}'

What to watch for in the real world

Standards land before the entire ecosystem catches up. Worth checking before you announce QUERY as your public search API:

Proxies, API gateways, and WAFs — some still allow-list only a handful of methods.
Browser and CDN behaviour — caching QUERY responses is more complex than GET; temporary Location URIs help.
Client libraries and OpenAPI codegen — support is improving, but pin versions carefully.
Logs and analytics — make sure QUERY is counted as a read, not lumped in with mutating POSTs.

For service-to-service APIs under your control, QUERY is already useful. For public browser-facing APIs, validate your edge stack and CORS setup first.

Why this matters

HTTP methods are how we communicate intent to every hop between the client and your app. When intent and method disagree — a read that intermediaries cannot assume from POST, or a body bolted onto GET — caches, retries, and security tooling all have to guess.

QUERY closes that gap with a small, carefully designed verb: safe, idempotent, cacheable, and allowed to carry a body. After more than a decade of drafts, RFC 10008 makes that contract official. If you maintain search or filter endpoints that never belonged in a URI, it is time to start planning for QUERY — especially on service-to-service paths you control, before you bet a public browser API on every gateway in the path understanding the verb.

2026-07 on Funky Si's Blog