What Is the New HTTP QUERY Method and How Does It Simplify Large Data Requests?

QUERY Method Definition

QUERY

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

Use Cases

When many parameters or large payloads need to be sent, embedding them in the URL can exceed length limits or be impractical. The QUERY method allows a JSON (or other) body to convey the data.

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

Using QUERY avoids the URL‑length problem:

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

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

Idempotence and Safety

A QUERY request is declared safe—it does not modify server state. Repeating the same request yields the same result, which aids caching and automatic retries.

Caching Mechanism

The response to a QUERY request is cacheable, similar to other HTTP methods. To improve cache efficiency, request bodies should be normalized (e.g., canonical formatting, removal of irrelevant encoding).

Accept-Query Response Header

Servers can advertise support for the QUERY method by including an Accept-Query header that lists the media types they can process.

Accept-Query: application/json, application/xml

Examples

Simple Direct 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 URL returns the same content.

Indirect 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 then performs a GET on the provided Location 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

Security best practices include avoiding sensitive data in URLs, preferring request bodies for query parameters, and when temporary resources are created to represent query results, not exposing raw request content in the URI.

The introduction of QUERY provides a flexible mechanism for large‑payload queries while preserving safety and idempotence, making it useful across many application scenarios.

For the full draft, see https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-05.html