RFC 10008: The HTTP `QUERY` Method

Document Metadata

Attribute	Detail
Publication Date	June 2026
Primary Author	J. Bishop
Working Group	HTTP (HTTPBIS)
Category	Proposed Standard
DOI	`https://doi.org/10.17487/RFC10008`
Stream	IETF

Abstract

This document establishes the QUERY method for the HTTP protocol. The purpose of a QUERY request is to ask a target resource to process a provided body of content in a manner that is both safe and idempotent, returning the result of that operation to the client.

While it shares the structural characteristic of POST (sending data in the request body), QUERY is designed so that requests can be automatically restarted or repeated by intermediaries without the risk of altering the server's state.

Status of This Memorandum

This is an Internet Standards Track document produced by the Internet Engineering Task Force (IETF). It has undergone public scrutiny and was approved for release by the Internet Engineering Steering Group (IESG).

For further details regarding Internet Standards, please refer to Section 2 of RFC 7841. Current status and errata can be found at https://www.rfc-editor.org/info/rfc10008.

1. Introduction

The QUERY method is introduced to facilitate requests that are safe and idempotent (as defined in Section 9.2 of [HTTP]) but require a representation of the query to be enclosed within the request body rather than the URI.

1.1 The Problem with `GET`

Traditionally, queries are handled via the GET method. For example:

GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 Host: example.org

However, relying solely on the URI for query parameters creates several bottlenecks:

~~Unlimited URI length~~ $\rightarrow$ Size limits are often unpredictable across various network hops (though $\ge 8000$ octets is recommended).
Inefficiency: Encoding complex data structures into a URI string is computationally expensive and verbose.
Privacy/Logging: URIs are frequently logged in plaintext, making them unsuitable for sensitive query data.
Resource Fragmentation: Every unique combination of query parameters is treated as a distinct resource URI.

1.2 The Problem with `POST`

To bypass GET limitations, developers often use POST:

POST /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

While this solves the data volume issue, it introduces a semantic problem: POST is not inherently safe or idempotent. Without external documentation, a client or proxy cannot know if a POST request is a read-only query or a state-changing command.

1.3 The `QUERY` Solution

The QUERY method bridges this gap. It allows the request body to carry the query parameters while explicitly signaling that the operation is safe.

Example of a QUERY request:

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

1.4 Technical Properties

The QUERY method adheres to the following mathematical and logical constraints:

Safety: The request does not modify the state of the resource.
Idempotency: Multiple identical requests have the same effect as a single request. $\text{Let } f \text{ be the request; then } f(x) = f(f(x))$

Comparison Logic

2. Implementation Goals

The following requirements must be met for a compliant QUERY implementation:

Support for enclosed request representations.
Guarantee of safety (no side effects).
Guarantee of idempotency (repeatable).
Ability for servers to assign URIs to specific queries or results.

3. Summary of Method Differences

Feature	`GET`	`POST`	`QUERY`
Body Allowed	No (usually)	Yes	Yes
Safe	Yes	No	Yes
Idempotent	Yes	No	Yes
Cacheable	Yes	Limited	Yes

This document is subject to BCP 78 and the IETF Trust's Legal Provisions. Code components are provided under the Revised BSD License.

RFC 10008: The HTTP QUERY Method