RFC 10008 gives HTTP a safe query method

Julian Reschke, James M. Snell and Mike Bishop use RFC 10008 to add QUERY to HTTP for one common API problem: clients need to send rich query input in a request body, while servers and intermediaries need the safety signals that GET already gives them.

Developers have worked around that gap for years. GET puts query data in the URI, which helps caches and bookmarks but strains URI length limits and exposes sensitive input in logs. POST accepts a body, but it gives intermediaries no standard signal that the request only asks for data. QUERY gives clients a body and tells the HTTP stack that the request remains safe and idempotent.

The method sits between GET and POST in the HTTP model. A client sends QUERY to a target resource, includes a Content-Type header, and places the query input in the request body. The server reads the body and returns the result. The client does not ask the server to change the target resource, and the client can repeat the same request after a failed connection.

That property has practical value for search APIs, analytics systems, document stores and data services. A complex filter may include JSONPath, SQL, XSLT or form data. URI encoding can make those inputs brittle. POST hides the semantics from shared infrastructure. QUERY gives API designers a standard verb for read operations that carry structured input.

The RFC also gives servers a way to connect body-based queries back to URI-based retrieval. A successful QUERY response can include Content-Location for the result resource. A client can later send GET to that URI and retrieve the same stored result. A server can also include Location for an equivalent resource that represents the query itself, which lets a client repeat the query through GET without resending the body.

That distinction matters. Content-Location points to a result the server produced for a given request. Location can point to a resource that re-runs the same query and returns the current result. API authors can choose between stable snapshots and reusable query handles, depending on product needs and storage costs.

Caching receives careful treatment in RFC 10008. Caches may store QUERY responses, but a cache key must include the request body and relevant metadata such as Content-Type. A cache may normalize insignificant differences, such as JSON formatting, if that normalization matches the resource's query semantics. Cache authors take on real risk there: if a cache treats two different queries as equivalent, it can serve the wrong response.

The RFC defines Accept-Query so a resource can advertise query formats. A server might return Accept-Query: application/jsonpath, application/sql to tell clients which request body formats it accepts for QUERY. That moves format discovery into HTTP instead of forcing developers to rely on endpoint documentation or trial requests.

Error handling also gains sharper lines. A server should reject a QUERY request without Content-Type. A server can use 415 when the resource does not support the media type, 400 when the body conflicts with the declared type, 422 when the syntax works but the query content fails, and 406 when the client asks for an unsupported response format.

Security trade-offs remain. QUERY can keep query input out of the URI, which reduces exposure in logs and bookmarks. Servers still need care when they mint Location or Content-Location URIs. If a request contains sensitive input, the generated URI should avoid leaking that input through path segments, query parameters or predictable identifiers.

Browser support will also shape adoption. The RFC notes that CORS user agents require a preflight request because QUERY does not belong to the CORS-safelisted method set in the Fetch standard. Web apps can still use QUERY, but teams must account for preflight latency and server CORS configuration.

QUERY will not replace GET. Short, shareable, cacheable queries still fit GET. QUERY helps when the query body carries enough structure or sensitivity that a URI becomes a poor container. POST still fits operations that create or change state. The new method gives API designers a name for one missing case: safe, repeatable reads with a body.

The broader change concerns HTTP semantics. Modern APIs often tunnel meaning through POST because the platform lacks a better verb for complex reads. RFC 10008 asks clients, servers, caches and frameworks to expose that meaning again. If library authors add first-class QUERY support, API teams can stop encoding read operations as state-changing requests and let HTTP infrastructure do more of the work it already knows how to do.