HTTP QUERY Method

QUERY is the HTTP method for the request every API eventually has and no existing method fits: a read whose parameters are too large, too structured, or too sensitive to put in a URL. Standardized as RFC 10008 in June 2026 — six years after draft-snell-search-method first proposed it in September 2020 — it is safe and idempotent like GET but carries a request body like POST. That combination is the entire point — it lets a server say this is a read in a way POST never could.

• Safe and idempotent, with a body - Registered in the IANA HTTP Method Registry as safe: yes, idempotent: yes. A QUERY may be automatically repeated or restarted without concern for partial state changes.
• Cacheable responses - A cache MAY satisfy subsequent QUERY requests from a stored response. The cache key MUST incorporate the request content, and caches MAY normalize semantically insignificant differences — content encodings, +json structural whitespace — before keying.
• Content-Location and Location - Content-Location claims the results are also retrievable by GET at that URI; Location claims a URI exists that repeats the query without resending the body. Two different promises, routinely conflated.
• The Accept-Query response header - A resource advertises QUERY support and the query media types it accepts, as a Structured Fields List. The RFC’s own example is Accept-Query: "application/jsonpath", application/sql;charset="UTF-8" — the method deliberately does not define a query language.
• No query language of its own - RFC 10008 specifies the envelope and leaves the content to a media type. What goes in the body is somebody else’s specification.

The reason this matters to anyone cataloguing APIs is that it retires a workaround that has been quietly distorting API design for twenty years. GET with a filter in the query string hits URL length limits, leaks parameters into logs and referrers, and cannot express nesting. So providers reach for POST /resource/search — and in doing so tell every cache, proxy, retry policy and OpenAPI generator in the path that the operation is unsafe and non-idempotent, which it is not. Every conditional request, every automatic retry, every cached response that a read should get, a search endpoint has been giving up. QUERY is how you stop paying that tax.

The tooling arrived alongside it. OpenAPI 3.1’s Path Item Object has a fixed set of method fields with no room for QUERY; 3.2 added additionalOperations, which is precisely how a method outside that set gets described. That is the practical gate — until a description format can express QUERY, no generated client, mock, or governance rule can reach it.

Accept-Query is the piece most relevant to discovery, and it is the piece nobody is using yet. It is a runtime, per-resource declaration of what query language this endpoint speaks — machine-readable, at the resource, without a documentation site. As of August 2026, zero of the 26,641 providers in the API Evangelist catalog declare it. That is not a criticism; the method is four months old. It is a baseline worth having on the record, because Accept-Query adoption is the cleanest single signal of whether QUERY is actually landing in production or living only in specification documents.

Note what RFC 10008 deliberately does not do: it defines no query language. The body is whatever media type the resource advertises, which is why the RFC’s example names application/jsonpath and application/sql. That leaves an obvious open slot directly above it — a filter grammar that a machine can validate. JSON Query Language is one early attempt at exactly that slot, and OData’s $filter and GraphQL are the incumbent answers that each require adopting a whole protocol to get at. QUERY is the HTTP-layer half of a two-part problem, and the half that is now settled.