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: November 3, 2022 | |||
J.M. Snell | J.M. Snell | |||
November 9, 2021 | May 2, 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 November 3, 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 34 ¶ | skipping to change at page 2, line 34 ¶ | |||
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 . . . . . 8 | |||
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 [RFCHTTP]), the QUERY method is used to ask the server | |||
to perform a query operation (described by the request payload) over | to 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 5, line 34 ¶ | skipping to change at page 5, line 34 ¶ | |||
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]. | [RFCHTTP]. | |||
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 8, line 23 ¶ | skipping to change at page 8, line 23 ¶ | |||
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>) | ||||
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. 14 change blocks. | ||||
15 lines changed or deleted | 24 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/ |