Introducing the New HTTP QUERY Method for Safe, Idempotent Data Requests

QUERY Method Definition

QUERY is a safe and idempotent HTTP request method that permits a request body. Unlike GET, it does not request a representation of a specific URI; instead, the server performs a query based on the request payload and returns the result.

Use Cases

When many parameters or large data need to be sent, embedding them in a URL becomes impractical. QUERY allows the payload to be placed in the request body.

GET /search?q=example&limit=10&sort=desc HTTP/1.1
Host: conardli.top

If the query parameters are numerous, the URL may exceed length limits. Using QUERY:

QUERY /search HTTP/1.1
Host: conardli.top
Content-Type: application/json

{
    "q": "ConardLi",
    "limit": 17,
    "sort": "desc"
}

Idempotency and Safety

Compared with POST, QUERY explicitly indicates that the operation is safe and does not modify server state, so repeated requests produce the same result. This property is useful for caching and automatic retries.

Cache Mechanism

Responses to QUERY are cacheable, similar to other HTTP methods. To improve cache efficiency, request bodies should be normalized (e.g., removing content encoding, applying a canonical format).

Accept-Query Response Header

Servers can signal support for the QUERY method by including an Accept-Query header that lists supported media types.

Accept-Query: application/json, application/xml

Examples

Simple Direct Query Response

QUERY /contacts HTTP/1.1
Host: conardli.top
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 17

Response:

HTTP/1.1 200 OK
Content-Type: text/csv

surname, givenname, email
Smith, John, [email protected]
Jones, Sally, [email protected]
Dubois, Camille, [email protected]

Response with Location and Content-Location

QUERY /contacts HTTP/1.1
Host: conardli.top
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 17

Response:

HTTP/1.1 200 OK
Content-Type: text/csv
Content-Location: /contacts/responses/42
Location: /contacts/queries/17

surname, givenname, email
Smith, John, [email protected]
Jones, Sally, [email protected]
Dubois, Camille, [email protected]

A subsequent GET of the Content-Location returns the same content.

Indirect Query Response (303 See Other)

QUERY /contacts HTTP/1.1
Host: conardli.top
Content-Type: example/query
Accept: text/csv

select surname, givenname, email limit 17

Response:

HTTP/1.1 303 See Other
Location: http://conardli.top/contacts/query123

The client follows the Location with a GET request to retrieve the result:

GET /contacts/query123 HTTP/1.1
Host: conardli.top
Accept: text/csv

Response:

HTTP/1.1 200 OK
Content-Type: text/csv

surname, givenname, email
Smith, John, [email protected]
Jones, Sally, [email protected]
Dubois, Camille, [email protected]

Final Considerations

Like other HTTP methods, QUERY requires careful security handling: avoid exposing sensitive data in URLs, prefer request bodies for parameters, and when creating temporary resources to represent query results, do not expose raw request content in the URI.

Reference draft: https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-05.html