QUERY request method
The QUERY HTTP method asks the target resource to process the request content in a safe and idempotent manner and return the result.
It is similar to POST because the query is carried in the request content, but unlike POST, QUERY is explicitly safe and idempotent.
This allows a QUERY request to be retried automatically without concern that it will cause additional changes to the target resource.
QUERY is useful when the query input is too large or complex for the target URI's query component.
The request's Content-Type header is required and determines how the request content is interpreted by the target resource.
| Request has body | Yes |
|---|---|
| Successful response has body | Yes |
| Safe | Yes |
| Idempotent | Yes |
| Cacheable | Yes |
| Allowed in HTML forms | No |
Syntax
QUERY <request-target>["?"<query>] HTTP/1.1
<request-target>-
Identifies the target resource that will process the query when combined with the information provided in the
Hostheader. This is an absolute path (e.g.,/path/to/resource) in requests to an origin server, and an absolute URL in requests to proxies (e.g.,https://example.com/path/to/resource). <query>Optional-
An optional URI query component preceded by a question mark (
?). It helps identify the resource being queried; the query operation itself is defined by the request content and its media type.
Examples
Querying a collection
The following request queries a contacts collection. The request content selects three fields, limits the response to ten results, and filters contacts by email address:
QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json
select=surname,givenname,email&limit=10&match=%22email=*@example.*%22
A successful response includes the query result in the response content:
HTTP/1.1 200 OK
Content-Type: application/json
[
{
"surname": "Smith",
"givenname": "John",
"email": "smith@example.org"
},
{
"surname": "Jones",
"givenname": "Sally",
"email": "sally.jones@example.com"
}
]
Specifications
| Specification |
|---|
| Unknown specification # section-2 |