draft-ietf-httpbis-safe-method-w-body-02.txt | draft-ietf-httpbis-safe-method-w-body-latest.txt | |||
---|---|---|---|---|
HTTP Working Group J. Reschke | HTTP Working Group J. Reschke | |||
Internet-Draft greenbytes | Internet-Draft greenbytes | |||
Intended status: Standards Track A. Malhotra | Intended status: Standards Track A. Malhotra | |||
Expires: May 13, 2022 | Expires: December 23, 2022 | |||
J.M. Snell | J.M. Snell | |||
November 9, 2021 | June 21, 2022 | |||
The HTTP QUERY Method | The HTTP QUERY Method | |||
draft-ietf-httpbis-safe-method-w-body-02 | draft-ietf-httpbis-safe-method-w-body-latest | |||
Abstract | Abstract | |||
This specification defines a new HTTP method, QUERY, as a safe, | This specification defines a new HTTP method, QUERY, as a safe, | |||
idempotent request method that can carry request content. | idempotent request method that can carry request content. | |||
Editorial Note | Editorial Note | |||
This note is to be removed before publishing as an RFC. | This note is to be removed before publishing as an RFC. | |||
Discussion of this draft takes place on the HTTP working group | Discussion of this draft takes place on the HTTP working group | |||
mailing list (ietf-http-wg@w3.org), which is archived at | mailing list (ietf-http-wg@w3.org), which is archived at | |||
<https://lists.w3.org/Archives/Public/ietf-http-wg/>. | <https://lists.w3.org/Archives/Public/ietf-http-wg/>. | |||
Working Group information can be found at <https://httpwg.org/>; | Working Group information can be found at <https://httpwg.org/>; | |||
source code and issues list for this draft can be found at | source code and issues list for this draft can be found at | |||
<https://github.com/httpwg/http-extensions/labels/safe-method- | <https://github.com/httpwg/http-extensions/labels/safe-method- | |||
w-body>. | w-body>. | |||
The changes in this draft are summarized in Appendix A.2. | The changes in this draft are summarized in Appendix A.3. | |||
Status of This Memo | Status of This Memo | |||
This Internet-Draft is submitted in full conformance with the | This Internet-Draft is submitted in full conformance with the | |||
provisions of BCP 78 and BCP 79. | provisions of BCP 78 and BCP 79. | |||
Internet-Drafts are working documents of the Internet Engineering | Internet-Drafts are working documents of the Internet Engineering | |||
Task Force (IETF). Note that other groups may also distribute | Task Force (IETF). Note that other groups may also distribute | |||
working documents as Internet-Drafts. The list of current Internet- | working documents as Internet-Drafts. The list of current Internet- | |||
Drafts is at https://datatracker.ietf.org/drafts/current/. | Drafts is at https://datatracker.ietf.org/drafts/current/. | |||
Internet-Drafts are draft documents valid for a maximum of six months | Internet-Drafts are draft documents valid for a maximum of six months | |||
and may be updated, replaced, or obsoleted by other documents at any | and may be updated, replaced, or obsoleted by other documents at any | |||
time. It is inappropriate to use Internet-Drafts as reference | time. It is inappropriate to use Internet-Drafts as reference | |||
material or to cite them other than as "work in progress." | material or to cite them other than as "work in progress." | |||
This Internet-Draft will expire on May 13, 2022. | This Internet-Draft will expire on December 23, 2022. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2021 IETF Trust and the persons identified as the | Copyright (c) 2022 IETF Trust and the persons identified as the | |||
document authors. All rights reserved. | document authors. All rights reserved. | |||
This document is subject to BCP 78 and the IETF Trust's Legal | This document is subject to BCP 78 and the IETF Trust's Legal | |||
Provisions Relating to IETF Documents (https://trustee.ietf.org/ | Provisions Relating to IETF Documents (https://trustee.ietf.org/ | |||
license-info) in effect on the date of publication of this document. | license-info) in effect on the date of publication of this document. | |||
Please review these documents carefully, as they describe your rights | Please review these documents carefully, as they describe your rights | |||
and restrictions with respect to this document. Code Components | and restrictions with respect to this document. Code Components | |||
extracted from this document must include Revised BSD License text as | extracted from this document must include Revised BSD License text as | |||
described in Section 4.e of the Trust Legal Provisions and are | described in Section 4.e of the Trust Legal Provisions and are | |||
provided without warranty as described in the Revised BSD License. | provided without warranty as described in the Revised BSD License. | |||
skipping to change at page 2, line 32 ¶ | skipping to change at page 2, line 32 ¶ | |||
2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 | 2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 4 | 2.1. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 5 | 3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 5 | |||
4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5 | 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
4.1. Simple QUERY with a Direct Response . . . . . . . . . . . 5 | 4.1. Simple QUERY with a Direct Response . . . . . . . . . . . 5 | |||
4.2. Simple QUERY with indirect response (303 See Other) . . . 6 | 4.2. Simple QUERY with indirect response (303 See Other) . . . 6 | |||
5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 | 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 | |||
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 | 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 | |||
7. Normative References . . . . . . . . . . . . . . . . . . . . 7 | 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 | |||
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 7 | Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 7 | |||
A.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 8 | A.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 7 | |||
A.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 8 | A.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 8 | |||
A.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 8 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 | |||
1. Introduction | 1. Introduction | |||
This specification defines the HTTP QUERY request method as a means | This specification defines the HTTP QUERY request method as a means | |||
of making a safe, idempotent request that contains content. | of making a safe, idempotent request that contains content. | |||
Most often, this is desirable when the data conveyed in a request is | Most often, this is desirable when the data conveyed in a request is | |||
too voluminous to be encoded into the request's URI. For example, | too voluminous to be encoded into the request's URI. For example, | |||
while this is an common and interoperable query: | while this is an common and interoperable query: | |||
skipping to change at page 3, line 19 ¶ | skipping to change at page 3, line 19 ¶ | |||
because it needs to be encoded to be a valid URI. | because it needs to be encoded to be a valid URI. | |||
Encoding query parameters directly into the request URI also | Encoding query parameters directly into the request URI also | |||
effectively casts every possible combination of query inputs as | effectively casts every possible combination of query inputs as | |||
distinct resources. Depending on the application, that may not be | distinct resources. Depending on the application, that may not be | |||
desirable. | desirable. | |||
As an alternative to using GET, many implementations make use of the | As an alternative to using GET, many implementations make use of the | |||
HTTP POST method to perform queries, as illustrated in the example | HTTP POST method to perform queries, as illustrated in the example | |||
below. In this case, the input parameters to the search operation | below. In this case, the input parameters to the search operation | |||
are passed along within the request payload as opposed to using the | are passed along within the request content as opposed to using the | |||
request URI. | request URI. | |||
A typical use of HTTP POST for requesting a search | A typical use of HTTP POST for requesting a search | |||
POST /feed HTTP/1.1 | POST /feed HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
Content-Type: application/x-www-form-urlencoded | Content-Type: application/x-www-form-urlencoded | |||
q=foo&limit=10&sort=-published | q=foo&limit=10&sort=-published | |||
This variation, however, suffers from the same basic limitation as | This variation, however, suffers from the same basic limitation as | |||
GET in that it is not readily apparent -- absent specific knowledge | GET in that it is not readily apparent -- absent specific knowledge | |||
of the resource and server to which the request is being sent -- that | of the resource and server to which the request is being sent -- that | |||
a safe, idempotent query is being performed. | a safe, idempotent query is being performed. | |||
The QUERY method provides a solution that spans the gap between the | The QUERY method provides a solution that spans the gap between the | |||
use of GET and POST. As with POST, the input to the query operation | use of GET and POST. As with POST, the input to the query operation | |||
is passed along within the payload of the request rather than as part | is passed along within the content of the request rather than as part | |||
of the request URI. Unlike POST, however, the method is explicitly | of the request URI. Unlike POST, however, the method is explicitly | |||
safe and idempotent, allowing functions like caching and automatic | safe and idempotent, allowing functions like caching and automatic | |||
retries to operate. | retries to operate. | |||
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | |||
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and | |||
"OPTIONAL" in this document are to be interpreted as described in BCP | "OPTIONAL" in this document are to be interpreted as described in BCP | |||
14 [RFC2119] [RFC8174] when, and only when, they appear in all | 14 [RFC2119] [RFC8174] when, and only when, they appear in all | |||
capitals, as shown here. | capitals, as shown here. | |||
2. QUERY | 2. QUERY | |||
The QUERY method is used to initiate a server-side query. Unlike the | The QUERY method is used to initiate a server-side query. Unlike the | |||
HTTP GET method, which requests that a server return a representation | HTTP GET method, which requests that a server return a representation | |||
of the resource identified by the target URI (as defined by | of the resource identified by the target URI (as defined by | |||
Section 7.1 of [RFCHTTP]), the QUERY method is used to ask the server | Section 7.1 of [HTTP]), the QUERY method is used to ask the server to | |||
to perform a query operation (described by the request payload) over | perform a query operation (described by the request content) over | |||
some set of data scoped to the effective request URI. The payload | some set of data scoped to the effective request URI. The content | |||
returned in response to a QUERY cannot be assumed to be a | returned in response to a QUERY cannot be assumed to be a | |||
representation of the resource identified by the effective request | representation of the resource identified by the effective request | |||
URI. | URI. | |||
The body payload of the request defines the query. Implementations | The content of the request defines the query. Implementations MAY | |||
MAY use a request body of any content type with the QUERY method, | use a request content of any media type with the QUERY method, | |||
provided that it has appropriate query semantics. | provided that it has appropriate query semantics. | |||
QUERY requests are both safe and idempotent with regards to the | QUERY requests are both safe and idempotent with regards to the | |||
resource identified by the request URI. That is, QUERY requests do | resource identified by the request URI. That is, QUERY requests do | |||
not alter the state of the targeted resource. However, while | not alter the state of the targeted resource. However, while | |||
processing a QUERY request, a server can be expected to allocate | processing a QUERY request, a server can be expected to allocate | |||
computing and memory resources or even create additional HTTP | computing and memory resources or even create additional HTTP | |||
resources through which the response can be retrieved. | resources through which the response can be retrieved. | |||
A successful response to a QUERY request is expected to provide some | A successful response to a QUERY request is expected to provide some | |||
skipping to change at page 4, line 41 ¶ | skipping to change at page 4, line 41 ¶ | |||
represented by a 204 No Content response. If the response includes | represented by a 204 No Content response. If the response includes | |||
content, it is expected to describe the results of the operation. In | content, it is expected to describe the results of the operation. In | |||
some cases, the server may choose to respond indirectly to the QUERY | some cases, the server may choose to respond indirectly to the QUERY | |||
request by returning a 3xx Redirection with a Location header field | request by returning a 3xx Redirection with a Location header field | |||
specifying an alternate Request URI from which the results can be | specifying an alternate Request URI from which the results can be | |||
retrieved using an HTTP GET request. Various non-normative examples | retrieved using an HTTP GET request. Various non-normative examples | |||
of successful QUERY responses are illustrated in Section 4. | of successful QUERY responses are illustrated in Section 4. | |||
The semantics of the QUERY method change to a "conditional QUERY" if | The semantics of the QUERY method change to a "conditional QUERY" if | |||
the request message includes an If-Modified-Since, If-Unmodified- | the request message includes an If-Modified-Since, If-Unmodified- | |||
Since, If-Match, If-None-Match, or If-Range header field ([RFCHTTP], | Since, If-Match, If-None-Match, or If-Range header field ([HTTP], | |||
Section 13). A conditional QUERY requests that the query be | Section 13). A conditional QUERY requests that the query be | |||
performed only under the circumstances described by the conditional | performed only under the circumstances described by the conditional | |||
header field(s). It is important to note, however, that such | header field(s). It is important to note, however, that such | |||
conditions are evaluated against the state of the target resource | conditions are evaluated against the state of the target resource | |||
itself as opposed to the collected results of the search operation. | itself as opposed to the collected results of the search operation. | |||
2.1. Caching | 2.1. Caching | |||
The response to a QUERY method is cacheable; a cache MAY use it to | The response to a QUERY method is cacheable; a cache MAY use it to | |||
satisfy subsequent QUERY requests as per Section 4 of | satisfy subsequent QUERY requests as per Section 4 of | |||
skipping to change at page 5, line 32 ¶ | skipping to change at page 5, line 32 ¶ | |||
3. The "Accept-Query" Header Field | 3. The "Accept-Query" Header Field | |||
The "Accept-Query" response header field MAY be used by a server to | The "Accept-Query" response header field MAY be used by a server to | |||
directly signal support for the QUERY method while identifying the | directly signal support for the QUERY method while identifying the | |||
specific query format media type(s) that may be used. | specific query format media type(s) that may be used. | |||
Accept-Query = 1#media-type | Accept-Query = 1#media-type | |||
The Accept-Query header field specifies a comma-separated listing of | The Accept-Query header field specifies a comma-separated listing of | |||
media types (with optional parameters) as defined by Section 8.3.1 of | media types (with optional parameters) as defined by Section 8.3.1 of | |||
[RFCHTTP]. | [HTTP]. | |||
The order of types listed by the Accept-Query header field is | The order of types listed by the Accept-Query header field is not | |||
insignificant. | significant. | |||
4. Examples | 4. Examples | |||
The non-normative examples in this section make use of a simple, | The non-normative examples in this section make use of a simple, | |||
hypothetical plain-text based query syntax based on SQL with results | hypothetical plain-text based query syntax based on SQL with results | |||
returned as comma-separated values. This is done for illustration | returned as comma-separated values. This is done for illustration | |||
purposes only. Implementations are free to use any format they wish | purposes only. Implementations are free to use any format they wish | |||
on both the request and response. | on both the request and response. | |||
4.1. Simple QUERY with a Direct Response | 4.1. Simple QUERY with a Direct Response | |||
skipping to change at page 7, line 8 ¶ | skipping to change at page 7, line 8 ¶ | |||
Content-Type: text/csv | Content-Type: text/csv | |||
surname, givenname, email | surname, givenname, email | |||
Smith, John, john.smith@example.org | Smith, John, john.smith@example.org | |||
Jones, Sally, sally.jones@example.com | Jones, Sally, sally.jones@example.com | |||
Dubois, Camille, camille.dubois@example.net | Dubois, Camille, camille.dubois@example.net | |||
5. Security Considerations | 5. Security Considerations | |||
The QUERY method is subject to the same general security | The QUERY method is subject to the same general security | |||
considerations as all HTTP methods as described in [RFCHTTP]. | considerations as all HTTP methods as described in [HTTP]. | |||
6. IANA Considerations | 6. IANA Considerations | |||
IANA is requested to add QUERY method in the permanent registry at | IANA is requested to add QUERY method in the permanent registry at | |||
<http://www.iana.org/assignments/http-methods> (see Section 16.1.1 of | <http://www.iana.org/assignments/http-methods> (see Section 16.1.1 of | |||
[RFCHTTP]). | [HTTP]). | |||
+-------------+------+------------+---------------+ | +-------------+------+------------+---------------+ | |||
| Method Name | Safe | Idempotent | Specification | | | Method Name | Safe | Idempotent | Specification | | |||
+-------------+------+------------+---------------+ | +-------------+------+------------+---------------+ | |||
| QUERY | Yes | Yes | Section 2 | | | QUERY | Yes | Yes | Section 2 | | |||
+-------------+------+------------+---------------+ | +-------------+------+------------+---------------+ | |||
Table 1 | Table 1 | |||
7. Normative References | 7. Normative References | |||
[HTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | ||||
Ed., "HTTP Semantics", STD 97, RFC 9110, | ||||
DOI 10.17487/RFC9110, June 2022, | ||||
<https://www.rfc-editor.org/info/rfc9110>. | ||||
[HTTP-CACHING] | [HTTP-CACHING] | |||
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | |||
Ed., "HTTP Semantics", Work in Progress, Internet-Draft, | Ed., "HTTP Caching", STD 98, RFC 9111, | |||
draft-ietf-httpbis-cache-19, September 10, 2021, | DOI 10.17487/RFC9111, June 2022, | |||
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis- | <https://www.rfc-editor.org/info/rfc9111>. | |||
cache-19>. | ||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | |||
Requirement Levels", BCP 14, RFC 2119, | Requirement Levels", BCP 14, RFC 2119, | |||
DOI 10.17487/RFC2119, March 1997, | DOI 10.17487/RFC2119, March 1997, | |||
<https://www.rfc-editor.org/info/rfc2119>. | <https://www.rfc-editor.org/info/rfc2119>. | |||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | |||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | |||
May 2017, <https://www.rfc-editor.org/info/rfc8174>. | May 2017, <https://www.rfc-editor.org/info/rfc8174>. | |||
[RFCHTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | ||||
Ed., "HTTP Semantics", Work in Progress, Internet-Draft, | ||||
draft-ietf-httpbis-semantics-19, September 10, 2021, | ||||
<https://datatracker.ietf.org/doc/html/draft-ietf-httpbis- | ||||
semantics-19>. | ||||
Appendix A. Change Log | Appendix A. Change Log | |||
This section is to be removed before publishing as an RFC. | This section is to be removed before publishing as an RFC. | |||
A.1. Since draft-ietf-httpbis-safe-method-w-body-00 | A.1. Since draft-ietf-httpbis-safe-method-w-body-00 | |||
o Use "example/query" media type instead of undefined "text/query" | o Use "example/query" media type instead of undefined "text/query" | |||
(<https://github.com/httpwg/http-extensions/issues/1450>) | (<https://github.com/httpwg/http-extensions/issues/1450>) | |||
o In Section 3, adjust the grammar to just define the field value | o In Section 3, adjust the grammar to just define the field value | |||
(<https://github.com/httpwg/http-extensions/issues/1470>) | (<https://github.com/httpwg/http-extensions/issues/1470>) | |||
o Update to latest HTTP core spec, and adjust terminology | o Update to latest HTTP core spec, and adjust terminology | |||
accordingly (<https://github.com/httpwg/http-extensions/ | accordingly (<https://github.com/httpwg/http-extensions/ | |||
issues/1473>) | issues/1473>) | |||
o Reference RFC 8174 and markup bcp14 terms | o Reference RFC 8174 and markup bcp14 terms | |||
(<https://github.com/httpwg/http-extensions/issues/1497>) | (<https://github.com/httpwg/http-extensions/issues/1497>) | |||
o Update HTTP reference (<https://github.com/httpwg/http-extensions/ | o Update HTTP reference (<https://github.com/httpwg/http-extensions/ | |||
issues/1524>) | issues/1524>) | |||
o Relax restriction of generic XML media type in request body | o Relax restriction of generic XML media type in request content | |||
(<https://github.com/httpwg/http-extensions/issues/1535>) | (<https://github.com/httpwg/http-extensions/issues/1535>) | |||
A.2. Since draft-ietf-httpbis-safe-method-w-body-01 | A.2. Since draft-ietf-httpbis-safe-method-w-body-01 | |||
o Add minimal description of cacheability | o Add minimal description of cacheability | |||
(<https://github.com/httpwg/http-extensions/issues/1552>) | (<https://github.com/httpwg/http-extensions/issues/1552>) | |||
o Use "QUERY" as method name (<https://github.com/httpwg/http- | o Use "QUERY" as method name (<https://github.com/httpwg/http- | |||
extensions/issues/1614>) | extensions/issues/1614>) | |||
o Update HTTP reference (<https://github.com/httpwg/http-extensions/ | o Update HTTP reference (<https://github.com/httpwg/http-extensions/ | |||
issues/1669>) | issues/1669>) | |||
A.3. Since draft-ietf-httpbis-safe-method-w-body-02 | ||||
o In Section 3, slightly rephrase statement about significance of | ||||
ordering (<https://github.com/httpwg/http-extensions/issues/1896>) | ||||
o Throughout: use "content" instead of "payload" or "body" | ||||
(<https://github.com/httpwg/http-extensions/issues/1915>) | ||||
o Updated references (<https://github.com/httpwg/http-extensions/ | ||||
issues/2157>) | ||||
Authors' Addresses | Authors' Addresses | |||
Julian Reschke | Julian Reschke | |||
greenbytes GmbH | greenbytes GmbH | |||
Hafenweg 16 | Hafenweg 16 | |||
48155 Münster | 48155 Münster | |||
Germany | Germany | |||
Email: julian.reschke@greenbytes.de | Email: julian.reschke@greenbytes.de | |||
URI: https://greenbytes.de/tech/webdav/ | URI: https://greenbytes.de/tech/webdav/ | |||
End of changes. 23 change blocks. | ||||
32 lines changed or deleted | 41 lines changed or added | |||
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/ |