draft-ietf-httpbis-safe-method-w-body-06.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: April 24, 2025 | Expires: June 10, 2025 | |||
J.M. Snell | J.M. Snell | |||
M. Bishop | M. Bishop | |||
Akamai | Akamai | |||
October 21, 2024 | December 7, 2024 | |||
The HTTP QUERY Method | The HTTP QUERY Method | |||
draft-ietf-httpbis-safe-method-w-body-06 | 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/query-method>. | <https://github.com/httpwg/http-extensions/labels/query-method>. | |||
The changes in this draft are summarized in Appendix A.6. | The changes in this draft are summarized in Appendix B.7. | |||
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 April 24, 2025. | This Internet-Draft will expire on June 10, 2025. | |||
Copyright Notice | Copyright Notice | |||
Copyright (c) 2024 IETF Trust and the persons identified as the | Copyright (c) 2024 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. | |||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 | |||
1.1. Notational Conventions . . . . . . . . . . . . . . . . . 4 | ||||
2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 | 2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
2.1. Content-Location and Location Fields . . . . . . . . . . 5 | 2.1. Content-Location and Location Fields . . . . . . . . . . 5 | |||
2.2. Redirection . . . . . . . . . . . . . . . . . . . . . . . 5 | 2.2. Redirection . . . . . . . . . . . . . . . . . . . . . . . 5 | |||
2.3. Conditional Requests . . . . . . . . . . . . . . . . . . 5 | 2.3. Conditional Requests . . . . . . . . . . . . . . . . . . 6 | |||
2.4. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 6 | 2.4. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 6 | |||
3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 6 | 3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 6 | |||
4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 7 | 4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 | |||
4.1. Simple QUERY with a Direct Response . . . . . . . . . . . 7 | 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 | |||
4.2. Simple QUERY with a Direct Response and Location | 5.1. Registration of QUERY method . . . . . . . . . . . . . . 8 | |||
Fields . . . . . . . . . . . . . . . . . . . . . . . . . 7 | 5.2. Registration of Accept-Query field . . . . . . . . . . . 8 | |||
4.3. Simple QUERY with Indirect Response (303 See Other) . . . 8 | 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 | |||
4.4. Simple QUERY with Redirect Response (308 Moved | 6.1. Normative References . . . . . . . . . . . . . . . . . . 9 | |||
Permanently) . . . . . . . . . . . . . . . . . . . . . . 9 | 6.2. Informative References . . . . . . . . . . . . . . . . . 9 | |||
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 | Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 9 | |||
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 | A.1. Simple QUERY with a Direct Response . . . . . . . . . . . 9 | |||
6.1. Registration of QUERY method . . . . . . . . . . . . . . 10 | A.2. Simple QUERY with a Direct Response and Location | |||
6.2. Registration of Accept-Query field . . . . . . . . . . . 10 | Fields . . . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
7. Normative References . . . . . . . . . . . . . . . . . . . . 11 | A.3. Simple QUERY with Indirect Response (303 See Other) . . . 11 | |||
Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 11 | A.4. Simple QUERY with Redirect Response (308 Moved | |||
A.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 11 | Permanently) . . . . . . . . . . . . . . . . . . . . . . 12 | |||
A.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 12 | Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 12 | |||
A.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 12 | B.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 12 | |||
A.4. Since draft-ietf-httpbis-safe-method-w-body-03 . . . . . 12 | B.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 13 | |||
A.5. Since draft-ietf-httpbis-safe-method-w-body-04 . . . . . 12 | B.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 13 | |||
A.6. Since draft-ietf-httpbis-safe-method-w-body-05 . . . . . 13 | B.4. Since draft-ietf-httpbis-safe-method-w-body-03 . . . . . 13 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 | B.5. Since draft-ietf-httpbis-safe-method-w-body-04 . . . . . 13 | |||
B.6. Since draft-ietf-httpbis-safe-method-w-body-05 . . . . . 14 | ||||
B.7. Since draft-ietf-httpbis-safe-method-w-body-06 . . . . . 14 | ||||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 | ||||
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: | this is a common query pattern: | |||
GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 | GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
if the query parameters extend to several kilobytes or more of data | However, for a query with parameters that are complex or large in | |||
it may not be, because many implementations place limits on their | size, encoding it in the request URI may not be the best option | |||
size. Often these limits are not known or discoverable ahead of | because | |||
time, because a request can pass through many uncoordinated systems. | ||||
Additionally, expressing certain kinds of data in the target URI is | ||||
inefficient, because it needs to be encoded to be a valid URI. | ||||
Encoding query parameters directly into the request URI also | o often size limits are not known ahead of time because a request | |||
effectively casts every possible combination of query inputs as | can pass through many uncoordinated system, | |||
distinct resources. Depending on the application, that may not be | ||||
desirable. | o expressing certain kinds of data in the target URI is inefficient | |||
because of the overhead of encoding that data into a valid URI, | ||||
and | ||||
o encoding query parameters 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 | 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 query operation are | below. In this case, the input parameters to the query operation are | |||
passed along within the request content as opposed to using the | passed along within the request content as opposed to using the | |||
request URI. | request URI. | |||
A typical use of HTTP POST for requesting a query: | A typical use of HTTP POST for requesting a query: | |||
POST /feed HTTP/1.1 | POST /feed HTTP/1.1 | |||
skipping to change at page 4, line 16 ¶ | skipping to change at page 4, line 19 ¶ | |||
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 | |||
As with POST, the input to the query operation is passed along within | As with POST, the input to the query operation is passed along within | |||
the content of the request rather than as part of the request URI. | the content of the request rather than as part of the request URI. | |||
Unlike POST, however, the method is explicitly safe and idempotent, | Unlike POST, however, the method is explicitly safe and idempotent, | |||
allowing functions like caching and automatic retries to operate. | allowing functions like caching and automatic retries to operate. | |||
Summarizing: | ||||
+------------+-------------+------------------+------------------+ | ||||
| | GET | QUERY | POST | | ||||
+------------+-------------+------------------+------------------+ | ||||
| Safe | yes | yes | potentially no | | ||||
| Idempotent | yes | yes | potentially no | | ||||
| Cacheable | yes | yes | no | | ||||
| Content | "no defined | expected | expected | | ||||
| (body) | semantics" | (semantics per | (semantics per | | ||||
| | | target resource) | target resource) | | ||||
+------------+-------------+------------------+------------------+ | ||||
Table 1 | ||||
1.1. Notational Conventions | ||||
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 | |||
skipping to change at page 5, line 37 ¶ | skipping to change at page 6, line 5 ¶ | |||
QUERY request by redirecting the user agent to a different URI (see | QUERY request by redirecting the user agent to a different URI (see | |||
Section 15.4 of [HTTP]). The semantics of the redirect response do | Section 15.4 of [HTTP]). The semantics of the redirect response do | |||
not differ from other methods. For instance, a 303 (See Other) | not differ from other methods. For instance, a 303 (See Other) | |||
response would indicate that the Location field identifies an | response would indicate that the Location field identifies an | |||
alternate URI from which the results can be retrieved using a GET | alternate URI from which the results can be retrieved using a GET | |||
request (this use case is also covered by the use of the Location | request (this use case is also covered by the use of the Location | |||
response field in a 2xx response). On the other hand, response codes | response field in a 2xx response). On the other hand, response codes | |||
307 (Temporary Redirect) and 308 (Permanent Redirect) can be used to | 307 (Temporary Redirect) and 308 (Permanent Redirect) can be used to | |||
request the user agent to redo the QUERY request on the URI specified | request the user agent to redo the QUERY request on the URI specified | |||
by the Location field. Various non-normative examples of successful | by the Location field. Various non-normative examples of successful | |||
QUERY responses are illustrated in Section 4. | QUERY responses are illustrated in Appendix A. | |||
2.3. Conditional Requests | 2.3. Conditional Requests | |||
The semantics of the QUERY method change to a "conditional QUERY" if | A conditional QUERY requests that the selected representation (i.e., | |||
the request message includes an If-Modified-Since, If-Unmodified- | the query results, after any content negotiation) be returned in the | |||
Since, If-Match, If-None-Match, or If-Range header field ([HTTP], | response only under the circumstances described by the conditional | |||
Section 13). A conditional QUERY requests that the query be | header field(s), as defined in Section 13 of [HTTP]. | |||
performed only under the circumstances described by the conditional | ||||
header field(s). It is important to note, however, that such | ||||
conditions are evaluated against the state of the target resource | ||||
itself as opposed to the collected results of the query operation. | ||||
2.4. Caching | 2.4. 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 | |||
[HTTP-CACHING]). | [HTTP-CACHING]). | |||
The cache key for a query (see Section 2 of [HTTP-CACHING]) MUST | The cache key for a query (see Section 2 of [HTTP-CACHING]) MUST | |||
incorporate the request content. When doing so, caches SHOULD first | incorporate the request content. When doing so, caches SHOULD first | |||
normalize request content to remove semantically insignificant | normalize request content to remove semantically insignificant | |||
skipping to change at page 6, line 30 ¶ | skipping to change at page 6, line 39 ¶ | |||
Type field (e.g., "+json") | Type field (e.g., "+json") | |||
o Normalizing based upon knowledge of the semantics of the content | o Normalizing based upon knowledge of the semantics of the content | |||
itself, as indicated by the request's Content-Type field. | itself, as indicated by the request's Content-Type field. | |||
Note that any such normalization is performed solely for the purpose | Note that any such normalization is performed solely for the purpose | |||
of generating a cache key; it does not change the request itself. | of generating a cache key; it does not change the request itself. | |||
3. The "Accept-Query" Header Field | 3. The "Accept-Query" Header Field | |||
The "Accept-Query" response header field MAY be used by a resource to | The "Accept-Query" response header field can be used by a resource 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" contains a list of media ranges (Section 12.5.1 of | |||
[HTTP]) using "Structured Fields" syntax ([STRUCTURED-FIELDS]). | ||||
Media ranges are represented by a List Structured Header Field of | ||||
either Tokens or Strings, containing the media range value without | ||||
parameters. Parameters, if any, are mapped to Parameters of type | ||||
String. | ||||
The Accept-Query header field specifies a comma-separated listing of | The choice of Token vs. String is semantically insignificant. That | |||
media types (with optional parameters) as defined by Section 8.3.1 of | is, recipients MAY convert Tokens to Strings, but MUST NOT process | |||
[HTTP]. | them differently based on the received type. | |||
// field syntax currently discussed in https://github.com/httpwg/ | ||||
// http-extensions/issues/2860 | ||||
The order of types listed by the Accept-Query header field is not | Media types do not exactly map to Tokens, for instance they allow a | |||
significant. | leading digit. In cases like these, the String format needs to be | |||
used. | ||||
The only supported uses of wildcards are "*/*", which matches any | ||||
type, or "xxxx/*", which matches any subtype of the indicated type. | ||||
The order of types listed in the field value is not significant. | ||||
The only allowed format for parameters is String. | ||||
Accept-Query's value applies to every URI on the server that shares | Accept-Query's value applies to every URI on the server that shares | |||
the same path; in other words, the query component is ignored. If | the same path; in other words, the query component is ignored. If | |||
requests to the same resource return different Accept-Query values, | requests to the same resource return different Accept-Query values, | |||
the most recently received fresh (per Section 4.2 of [HTTP-CACHING]) | the most recently received fresh value (per Section 4.2 of | |||
value is used. | [HTTP-CACHING]) is used. | |||
4. Examples | Example: | |||
Accept-Query: "application/jsonpath", application/sql;charset="UTF-8" | ||||
Although the syntax for this field appears to be similar to other | ||||
fields, such as "Accept" (Section 12.5.1 of [HTTP]), it is a | ||||
Structured Field and thus MUST be processed as specified in Section 4 | ||||
of [STRUCTURED-FIELDS]. | ||||
4. Security Considerations | ||||
The QUERY method is subject to the same general security | ||||
considerations as all HTTP methods as described in [HTTP]. | ||||
It can be used as an alternative to passing request information in | ||||
the URI (e.g., in the query section). This is preferred in some | ||||
cases, as the URI is more likely to be logged or otherwise processed | ||||
by intermediaries than the request content. If a server creates a | ||||
temporary resource to represent the results of a QUERY request (e.g., | ||||
for use in the Location or Content-Location field) and the request | ||||
contains sensitive information that cannot be logged, then the URI of | ||||
this resource SHOULD be chosen such that it does not include any | ||||
sensitive portions of the original request content. | ||||
Caches that normalize QUERY content incorrectly or in ways that are | ||||
significantly different than how the resource processes the content | ||||
can return the incorrect response if normalization results in a false | ||||
positive. | ||||
A QUERY request from user agents implementing CORS (Cross-Origin | ||||
Resource Sharing) will require a "preflight" request, as QUERY does | ||||
not belong to the set of CORS-safelisted methods (see "Methods | ||||
(https://fetch.spec.whatwg.org/#methods)" in [FETCH]). | ||||
5. IANA Considerations | ||||
5.1. Registration of QUERY method | ||||
IANA is requested to add the QUERY method to the HTTP Method Registry | ||||
at <http://www.iana.org/assignments/http-methods> (see Section 16.3.1 | ||||
of [HTTP]). | ||||
+-------------+------+------------+---------------+ | ||||
| Method Name | Safe | Idempotent | Specification | | ||||
+-------------+------+------------+---------------+ | ||||
| QUERY | Yes | Yes | Section 2 | | ||||
+-------------+------+------------+---------------+ | ||||
Table 2 | ||||
5.2. Registration of Accept-Query field | ||||
IANA is requested to add the Accept-Query field to the HTTP Field | ||||
Name Registry at <https://www.iana.org/assignments/http-fields> (see | ||||
Section 16.1.1 of [HTTP]). | ||||
+------------+---------+----------+---------+---------------------+ | ||||
|Field Name |Status |Structured|Reference| Comments | | ||||
| | |Type | | | | ||||
+------------+---------+----------+---------+---------------------+ | ||||
|Accept-Query|permanent| |Section 3| | | ||||
| | | |of this | // field syntax | | ||||
| | | |document.| currently discussed | | ||||
| | | | | in | | ||||
| | | | | https://github.com/ | | ||||
| | | | | httpwg/ | | ||||
| | | | | // http-extensions/ | | ||||
| | | | | issues/2860 | | ||||
+------------+---------+----------+---------+---------------------+ | ||||
Table 3 | ||||
6. References | ||||
6.1. 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] | ||||
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | ||||
Ed., "HTTP Caching", STD 98, RFC 9111, | ||||
DOI 10.17487/RFC9111, June 2022, | ||||
<https://www.rfc-editor.org/info/rfc9111>. | ||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | ||||
Requirement Levels", BCP 14, RFC 2119, | ||||
DOI 10.17487/RFC2119, March 1997, | ||||
<https://www.rfc-editor.org/info/rfc2119>. | ||||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | ||||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | ||||
May 2017, <https://www.rfc-editor.org/info/rfc8174>. | ||||
[STRUCTURED-FIELDS] | ||||
Nottingham, M. and P-H. Kamp, "Structured Field Values for | ||||
HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024, | ||||
<https://www.rfc-editor.org/info/rfc9651>. | ||||
6.2. Informative References | ||||
[FETCH] WHATWG, "FETCH", <https://fetch.spec.whatwg.org>. | ||||
Appendix A. 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 | A.1. Simple QUERY with a Direct Response | |||
A simple query with a direct response: | A simple query with a direct response: | |||
QUERY /contacts HTTP/1.1 | QUERY /contacts HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
Content-Type: example/query | Content-Type: application/sql | |||
Accept: text/csv | Accept: text/csv | |||
select surname, givenname, email limit 10 | select surname, givenname, email limit 10 | |||
Response: | Response: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
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 | |||
4.2. Simple QUERY with a Direct Response and Location Fields | A.2. Simple QUERY with a Direct Response and Location Fields | |||
A simple query with a direct response: | A simple query with a direct response: | |||
QUERY /contacts HTTP/1.1 | QUERY /contacts HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
Content-Type: example/query | Content-Type: application/sql | |||
Accept: text/csv | Accept: text/csv | |||
select surname, givenname, email limit 10 | select surname, givenname, email limit 10 | |||
Response: | Response: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Content-Type: text/csv | Content-Type: text/csv | |||
Content-Location: /contacts/responses/42 | Content-Location: /contacts/responses/42 | |||
Location: /contacts/queries/17 | Location: /contacts/queries/17 | |||
skipping to change at page 8, line 35 ¶ | skipping to change at page 11, line 19 ¶ | |||
Response: | Response: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
Content-Type: text/csv | Content-Type: text/csv | |||
Content-Location: /contacts/responses/43 | Content-Location: /contacts/responses/43 | |||
surname, givenname, email | surname, givenname, email | |||
Jones, Sally, sally.jones@example.com | Jones, Sally, sally.jones@example.com | |||
Dubois, Camille, camille.dubois@example.net | Dubois, Camille, camille.dubois@example.net | |||
4.3. Simple QUERY with Indirect Response (303 See Other) | A.3. Simple QUERY with Indirect Response (303 See Other) | |||
A simple query with an Indirect Response (303 See Other): | A simple query with an Indirect Response (303 See Other): | |||
QUERY /contacts HTTP/1.1 | QUERY /contacts HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
Content-Type: example/query | Content-Type: application/sql | |||
Accept: text/csv | Accept: text/csv | |||
select surname, givenname, email limit 10 | select surname, givenname, email limit 10 | |||
Response: | Response: | |||
HTTP/1.1 303 See Other | HTTP/1.1 303 See Other | |||
Location: /contacts/query123 | Location: /contacts/query123 | |||
Retrieval of the Query Response: | Retrieval of the Query Response: | |||
skipping to change at page 9, line 18 ¶ | skipping to change at page 12, line 5 ¶ | |||
Response: | Response: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
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 | |||
4.4. Simple QUERY with Redirect Response (308 Moved Permanently) | A.4. Simple QUERY with Redirect Response (308 Moved Permanently) | |||
A simple query being redirected: | A simple query being redirected: | |||
QUERY /contacts HTTP/1.1 | QUERY /contacts HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
Content-Type: example/query | Content-Type: application/sql | |||
Accept: text/csv | Accept: text/csv | |||
select surname, givenname, email limit 10 | select surname, givenname, email limit 10 | |||
Response: | Response: | |||
HTTP/1.1 308 Moved Permanently | HTTP/1.1 308 Moved Permanently | |||
Location: /morecontacts | Location: /morecontacts | |||
Redirected request: | Redirected request: | |||
QUERY /morecontacts HTTP/1.1 | QUERY /morecontacts HTTP/1.1 | |||
Host: example.org | Host: example.org | |||
Content-Type: example/query | Content-Type: application/sql | |||
Accept: text/csv | Accept: text/csv | |||
select surname, givenname, email limit 10 | select surname, givenname, email limit 10 | |||
Response: | Response: | |||
HTTP/1.1 200 OK | HTTP/1.1 200 OK | |||
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 | Appendix B. Change Log | |||
The QUERY method is subject to the same general security | ||||
considerations as all HTTP methods as described in [HTTP]. | ||||
The QUERY method can be used as an alternative to passing query | ||||
information in the query portion of a URI. This is preferred in some | ||||
cases, as the URI is more likely to be logged than the request | ||||
content. If a server creates a temporary resource to represent the | ||||
results of a QUERY request (e.g., for use in the Location or Content- | ||||
Location field) and the request contains sensitive information that | ||||
cannot be logged, then the URI of this resource SHOULD be chosen such | ||||
that it does not include any sensitive portions of the original | ||||
request content. | ||||
6. IANA Considerations | ||||
6.1. Registration of QUERY method | ||||
IANA is requested to add the QUERY method to the HTTP Method Registry | ||||
at <http://www.iana.org/assignments/http-methods> (see Section 16.3.1 | ||||
of [HTTP]). | ||||
+-------------+------+------------+---------------+ | ||||
| Method Name | Safe | Idempotent | Specification | | ||||
+-------------+------+------------+---------------+ | ||||
| QUERY | Yes | Yes | Section 2 | | ||||
+-------------+------+------------+---------------+ | ||||
Table 1 | ||||
6.2. Registration of Accept-Query field | ||||
IANA is requested to add the Accept-Query field to the HTTP Field | ||||
Name Registry at <https://www.iana.org/assignments/http-fields> (see | ||||
Section 16.1.1 of [HTTP]). | ||||
+------------+---------+----------+---------+---------------------+ | ||||
|Field Name |Status |Structured|Reference| Comments | | ||||
| | |Type | | | | ||||
+------------+---------+----------+---------+---------------------+ | ||||
|Accept-Query|permanent| |Section 3| | | ||||
| | | |of this | // field syntax | | ||||
| | | |document.| currently discussed | | ||||
| | | | | in | | ||||
| | | | | https://github.com/ | | ||||
| | | | | httpwg/ | | ||||
| | | | | // http-extensions/ | | ||||
| | | | | issues/2860 | | ||||
+------------+---------+----------+---------+---------------------+ | ||||
Table 2 | ||||
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] | ||||
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, | ||||
Ed., "HTTP Caching", STD 98, RFC 9111, | ||||
DOI 10.17487/RFC9111, June 2022, | ||||
<https://www.rfc-editor.org/info/rfc9111>. | ||||
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate | ||||
Requirement Levels", BCP 14, RFC 2119, | ||||
DOI 10.17487/RFC2119, March 1997, | ||||
<https://www.rfc-editor.org/info/rfc2119>. | ||||
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC | ||||
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, | ||||
May 2017, <https://www.rfc-editor.org/info/rfc8174>. | ||||
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 | B.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 content | 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 | B.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 | B.3. Since draft-ietf-httpbis-safe-method-w-body-02 | |||
o In Section 3, slightly rephrase statement about significance of | o In Section 3, slightly rephrase statement about significance of | |||
ordering (<https://github.com/httpwg/http-extensions/issues/1896>) | ordering (<https://github.com/httpwg/http-extensions/issues/1896>) | |||
o Throughout: use "content" instead of "payload" or "body" | o Throughout: use "content" instead of "payload" or "body" | |||
(<https://github.com/httpwg/http-extensions/issues/1915>) | (<https://github.com/httpwg/http-extensions/issues/1915>) | |||
o Updated references (<https://github.com/httpwg/http-extensions/ | o Updated references (<https://github.com/httpwg/http-extensions/ | |||
issues/2157>) | issues/2157>) | |||
A.4. Since draft-ietf-httpbis-safe-method-w-body-03 | B.4. Since draft-ietf-httpbis-safe-method-w-body-03 | |||
o In Section 3, clarify scope (<https://github.com/httpwg/http- | o In Section 3, clarify scope (<https://github.com/httpwg/http- | |||
extensions/issues/1913>) | extensions/issues/1913>) | |||
A.5. Since draft-ietf-httpbis-safe-method-w-body-04 | B.5. Since draft-ietf-httpbis-safe-method-w-body-04 | |||
o Describe role of Content-Location and Location fields | o Describe role of Content-Location and Location fields | |||
(<https://github.com/httpwg/http-extensions/issues/1745>) | (<https://github.com/httpwg/http-extensions/issues/1745>) | |||
o Added Mike Bishop as author (<https://github.com/httpwg/http- | o Added Mike Bishop as author (<https://github.com/httpwg/http- | |||
extensions/issues/2837>) | extensions/issues/2837>) | |||
o Use "target URI" instead of "effective request URI" | o Use "target URI" instead of "effective request URI" | |||
(<https://github.com/httpwg/http-extensions/issues/2883>) | (<https://github.com/httpwg/http-extensions/issues/2883>) | |||
A.6. Since draft-ietf-httpbis-safe-method-w-body-05 | B.6. Since draft-ietf-httpbis-safe-method-w-body-05 | |||
o Updated language and examples about redirects and method rewriting | o Updated language and examples about redirects and method rewriting | |||
(<https://github.com/httpwg/http-extensions/issues/1917>) | (<https://github.com/httpwg/http-extensions/issues/1917>) | |||
o Add QUERY example to introduction (<https://github.com/httpwg/ | o Add QUERY example to introduction (<https://github.com/httpwg/ | |||
http-extensions/issues/2171>) | http-extensions/issues/2171>) | |||
o Update "Sensitive information in QUERY URLs" | o Update "Sensitive information in QUERY URLs" | |||
(<https://github.com/httpwg/http-extensions/issues/2853>) | (<https://github.com/httpwg/http-extensions/issues/2853>) | |||
o Field registration for "Accept-Query" (<https://github.com/httpwg/ | o Field registration for "Accept-Query" (<https://github.com/httpwg/ | |||
http-extensions/issues/2903>) | http-extensions/issues/2903>) | |||
B.7. Since draft-ietf-httpbis-safe-method-w-body-06 | ||||
o Improve language about sensitive information in URIs | ||||
(<https://github.com/httpwg/http-extensions/issues/1895>) | ||||
o Clarified description of conditional queries | ||||
(<https://github.com/httpwg/http-extensions/issues/1917>) | ||||
o Editorial changes to Introduction (ack Will Hawkins, | ||||
<https://github.com/httpwg/http-extensions/pull/2859>) | ||||
o Added Security Consideration with respect to Normalization | ||||
(<https://github.com/httpwg/http-extensions/issues/2896>) | ||||
o Added CORS considerations (<https://github.com/httpwg/http- | ||||
extensions/issues/2898>) | ||||
o Make Accept-Query a Structured Field (<https://github.com/httpwg/ | ||||
http-extensions/issues/2934>) | ||||
o SQL media type is application/sql (RFC6922) | ||||
(<https://github.com/httpwg/http-extensions/issues/2936>) | ||||
o Added overview table to introduction (<https://github.com/httpwg/ | ||||
http-extensions/issues/2951>) | ||||
o Moved BCP14 related text into subsection | ||||
(<https://github.com/httpwg/http-extensions/issues/2954>) | ||||
o Move examples into index (<https://github.com/httpwg/http- | ||||
extensions/issues/2957>) | ||||
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. 37 change blocks. | ||||
149 lines changed or deleted | 243 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/ |