RFC 10008: The HTTP QUERY Method | RFC Editor

Open Original Page

RFC 10008: The HTTP QUERY Method | RFC Editor

Skip to content The RFC Series

Contents About this RFC Errata

1.2 Notational Conventions

2.1 Media Types and Content Negotiation

2.2 Equivalent Resource

2.3 Content-Location Response Field

2.4 Location Response Field

2.6 Conditional Requests

3 The Accept-Query Header Field

4 Security Considerations

5 IANA Considerations

5.1 Registration of the QUERY Method

5.2 Registration of the Accept-Query Field

6.1 Normative References

6.2 Informative References

A.2 Discovery of QUERY Support

A.3 Discovery of QUERY Formats

A.4 Content-Location, Location, and Indirect Responses

A.4.1 Using Content-Location

A.4.2 Using Location

A.4.3 Indirect Responses

A.5 Conditional Requests

A.6 More Query Formats

Appendix B Selection of the Method Name 'QUERY'

RFC 10008: The HTTP QUERY Method

This specification defines the QUERY method for HTTP.
A QUERY requests that the request target process the enclosed
content in a safe and idempotent manner and then respond with the
result of that processing. This is similar to POST requests, but QUERY requests
can be automatically repeated or restarted without concern for
partial state changes.¶

This is an Internet Standards Track document.¶

This document is a product of the Internet Engineering Task Force
(IETF). It represents the consensus of the IETF community. It has
received public review and has been approved for publication by
the Internet Engineering Steering Group (IESG). Further
information on Internet Standards is available in Section 2 of
RFC 7841.¶

Information about the current status of this document, any
errata, and how to provide feedback on it may be obtained at
https://www.rfc-editor.org/info/rfc10008.¶

Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with
respect to this document. Code Components extracted from this
document must include Revised BSD License text as described in
Section 4.e of the Trust Legal Provisions and are provided without
warranty as described in the Revised BSD License.¶

This specification defines the HTTP QUERY request method as a means of
making a safe, idempotent request (Section 9.2 of [HTTP]) that
encloses a representation describing how the request is to be processed by the target resource.¶

A common query pattern is:¶

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

However, when the data conveyed is too voluminous to be encoded in the request's URI,
this pattern becomes problematic:¶

size limits often are not known ahead of time because a request can pass through many uncoordinated
systems (but note that Section 4.1 of [HTTP] recommends senders and recipients to support at least 8000 octets),¶

expressing certain kinds of data in the target URI is inefficient because of the overhead of encoding that data into a valid URI,¶

request URIs are more likely to be logged than request content and may also turn up in bookmarks,¶

encoding queries directly into the request URI effectively casts every possible combination of query inputs as distinct
resources.¶

As an alternative to using GET, many implementations make use of the
HTTP POST method to perform queries, as illustrated in the example
below. In this case, the input to the query operation is
passed as the request content as opposed to using the
request URI's query component.¶

A typical use of HTTP POST for requesting a query is:¶

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

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

In this variation, however, it is not readily apparent -- without specific knowledge of the
resource and server to which the request is being sent -- that a safe,
idempotent query is being performed.¶

The QUERY method provides a solution that spans the gap between the use of GET and POST, with
the example above being expressed as:¶

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

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

As with POST, the input to the query operation is passed as the content of the request
rather than as part of the request URI. Unlike POST, however, the method is explicitly safe
and idempotent, allowing functions like caching and automatic retries to operate.¶

Recognizing the design principle that any important resource ought to be
identified by a URI, this specification describes how a server can assign URIs to both
the query itself or to a specific query result, for later use in a GET request.¶

Table 1:
Summary of Relevant Method Properties

Safe
yes
yes
potentially no

Idempotent
yes
yes
potentially no

URI for query itself
yes (by definition)
optional (Location response field)
no

URI for query result
optional (Content-Location response field)
optional (Content-Location response field)
optional (Content-Location response field)

Cacheable
yes
yes
yes, but only for future GET or HEAD requests

Content (body)
"no defined semantics"
expected (semantics per target resource)
expected (semantics per target resource)

This document uses terminology defined in Section 3 of [HTTP].¶

Furthermore, it uses the terms URI query parameter for parameters
in the query component of a URI (Section 4.2.2 of [HTTP]) and
query content for the request content (Section 6.4 of [HTTP])
of a QUERY request.¶

1.2. Notational Conventions

Links

Browse another page: