RFC 10008: The HTTP QUERY Method

Overview

RFC 10008 defines the QUERY method for HTTP, establishing a standardized way to perform server-side queries that require a request body while remaining safe and idempotent. This method solves a long-standing architectural tension where developers had to choose between GET (which is safe and idempotent but limited by URI length) and POST (which supports large bodies but is neither inherently safe nor idempotent).

By explicitly defining QUERY as safe and idempotent, the IETF enables automatic retries, caching, and the use of conditional requests for complex queries that would otherwise be forced into POST requests.

Core Semantics of the QUERY Method

Safe and Idempotent Processing

The QUERY method is designed to be safe, meaning it does not request or expect any change to the state of the target resource. It is also idempotent, meaning the request can be repeated or restarted (e.g., after a connection failure) without causing partial state changes or side effects. This distinguishes it from POST, which is generally used for state-changing operations.

Request and Response Structure

  • Request Content: Unlike GET, a QUERY request expects a body (query content) and a Content-Type header. Servers must fail the request if the Content-Type is missing or inconsistent with the content.
  • Success Responses: A 200 (OK) response indicates the query was successfully processed, with the results enclosed in the response body.
  • Resource Identification: While the query is defined by the request body, the target URI still identifies the resource being queried. The URI's query part may also be used to further identify the resource.

Bridging GET and POST

RFC 10008 provides a formal mechanism to transition from a QUERY request to a GET request through the use of specific response headers. This allows clients to simplify subsequent requests by avoiding the need to resend the query body.

Equivalent Resources

An "equivalent resource" is a virtual resource that represents the specific QUERY request and its target. If a server assigns a URI to this equivalent resource, it can be returned in the Location header of a 2xx response. A client can then use a GET request to that URI to repeat the query without resending the body.

Result Identification

Servers may use the Content-Location header to provide a URI for the specific results of a query operation. This URI may be temporary and allows the client to retrieve the results again via GET.

Caching and Conditional Requests

Cache Key Requirements

Responses to QUERY requests are cacheable. However, because the query is defined by the body rather than the URI, the cache key must incorporate the request content and its related metadata. Caches may perform semantic normalization (e.g., removing insignificant whitespace) to improve efficiency, unless the client specifies the no-transform directive.

Conditional Requests

QUERY supports conditional requests using standard HTTP conditional headers. A client can request that results be returned only if they have changed since the last request, allowing the server to respond with 304 (Not Modified) to save bandwidth.

Discovery and Negotiation

The Accept-Query Header

To signal support for the QUERY method and specify which query formats are accepted, servers can use the Accept-Query response header. This is a Structured Field that lists supported media ranges (e.g., application/sql or application/jsonpath).

Method Discovery

Clients can discover QUERY support using the OPTIONS method, which returns the Allow header listing supported methods, or by attempting a QUERY request and handling a 405 (Method Not Allowed) response.

Security and Implementation Considerations

Privacy and Logging

Using QUERY is preferred over GET when the query contains sensitive information, as request bodies are less likely to be logged by intermediaries than URIs. However, RFC 10008 recommends that any URIs generated for equivalent resources (via Location or Content-Location) should not include sensitive portions of the original request content.

CORS and Preflight

Because QUERY is not among the CORS-safelisted methods, any cross-origin request using QUERY will require a CORS preflight request.

Community Perspectives

Discussion among developers highlights both the utility and the potential friction of adopting a new HTTP method:

  • Utility for AI and Streaming: Some developers note that QUERY could resolve issues with EventSource (which only supports GET), enabling streaming AI queries that require request bodies without hacking the protocol.
  • Concerns over Cache Keys: Critics argue that including the request body in the cache key is problematic, noting that user-controlled bodies could lead to trivial cache-busting attacks or that complex caching logic usually happens below the HTTP layer.
  • Adoption Friction: There is a general concern that the "plumbing" required to support a new method across all intermediaries and clients may hinder widespread adoption, despite the technical merits.
  • Form Integration: There is interest in seeing HTML forms support method="query" to eliminate the browser's "confirm form resubmission" warnings associated with POST refreshes.

Sources