QUERY method

Defined meaning

QUERY asks the target resource to perform a query operation using the enclosed content, then return the result. The target resource defines the operation’s scope. The request content and its media type define the query.

QUERY /records HTTP/1.1
Host: example.invalid
Content-Type: application/json
Accept: application/json
Content-Length: 29

{"status":"active","limit":2}

Expected result: /records processes the JSON query without the client requesting a change to the target resource. A successful 200 OK response contains the query result.

QUERY is not another name for a URI query component and does not imply SQL. A resource can define JSON, form data, SQL, JSONPath, or another registered media type as its query format.

Properties

QUERY is safe and idempotent. The client does not request a state change, and an identical request can be retried or repeated without changing the intended effect. Incidental server effects such as logging or metrics do not change those method properties.

Request content is expected. A server must fail a QUERY request when Content-Type is missing or inconsistent with the content. Typical failures include:

• 400 Bad Request when media type information is absent or content is invalid for the declared type.
• 406 Not Acceptable when the resource cannot produce an acceptable response representation.
• 415 Unsupported Media Type when the resource does not support the declared query format.
• 422 Unprocessable Content when the format is valid but the query itself cannot be processed.

Discovery and supported formats

An OPTIONS response can advertise QUERY in Allow. The Accept-Query response field directly advertises QUERY support and the accepted query media types using Structured Fields syntax.

HTTP/1.1 204 No Content
Allow: GET, HEAD, QUERY, OPTIONS
Accept-Query: "application/json", "application/sql"

Expected result: a client can discover both the method and the two query content formats before sending a QUERY request.

Accept-Query describes request formats accepted by QUERY. It is different from the request field Accept, which describes response formats the client accepts.

Result resources and identifiers

A successful response can include Content-Location to identify a resource corresponding to the result that was returned. It can include Location to identify an equivalent resource that a client can later retrieve with GET to repeat the query without resending its content. Those fields make different claims and neither is required.

Conditional requests and caching

QUERY responses are cacheable. A cache key must incorporate the request content and related metadata, so correct QUERY caching is more involved than ordinary GET caching. A server can simplify later reuse by providing a Location for an equivalent GET resource.

Conditional request fields apply to the selected representation of the equivalent resource. For example, a conditional QUERY can receive 304 Not Modified when its validator matches.

Redirects and browser CORS

For 301, 302, 307, and 308, the redirected request remains QUERY; the special permission to rewrite some POST requests to GET does not apply. A 303 See Other directs the client to retrieve another resource, normally with GET.

Cross-origin browser QUERY requests require an OPTIONS preflight because QUERY is not a CORS-safelisted method. The server must authorize QUERY in Access-Control-Allow-Methods and authorize any non-safelisted request fields.

Common mistake

Do not use QUERY as a way to disguise an operation that changes application state. If the client is requesting a state change, QUERY’s safe semantics are the wrong contract even when the operation also returns data.