draft-ietf-httpbis-safe-method-w-body-08.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 J.M. Snell
Expires: August 29, 2025 Expires: September 7, 2025
J.M. Snell
M. Bishop M. Bishop
Akamai Akamai
February 25, 2025 March 6, 2025
The HTTP QUERY Method The HTTP QUERY Method
draft-ietf-httpbis-safe-method-w-body-08 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 B.8. The changes in this draft are summarized in Appendix B.9.
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 August 29, 2025.
This Internet-Draft will expire on September 7, 2025.
Copyright Notice Copyright Notice
Copyright (c) 2025 IETF Trust and the persons identified as the Copyright (c) 2025 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. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 4 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 5
2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. QUERY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Content-Location and Location Fields . . . . . . . . . . 5 2.1. Content-Location and Location Fields . . . . . . . . . . 5
2.2. Redirection . . . . . . . . . . . . . . . . . . . . . . . 6 2.2. Redirection . . . . . . . . . . . . . . . . . . . . . . . 6
2.3. Conditional Requests . . . . . . . . . . . . . . . . . . 6 2.3. Conditional Requests . . . . . . . . . . . . . . . . . . 6
2.4. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 6 2.4. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5. Range Requests . . . . . . . . . . . . . . . . . . . . . 7 2.5. Range Requests . . . . . . . . . . . . . . . . . . . . . 7
3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 7 3. The "Accept-Query" Header Field . . . . . . . . . . . . . . . 7
4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
5.1. Registration of QUERY method . . . . . . . . . . . . . . 8 5.1. Registration of QUERY method . . . . . . . . . . . . . . 8
5.2. Registration of Accept-Query field . . . . . . . . . . . 8 5.2. Registration of Accept-Query field . . . . . . . . . . . 9
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. Normative References . . . . . . . . . . . . . . . . . . 9 6.1. Normative References . . . . . . . . . . . . . . . . . . 9
6.2. Informative References . . . . . . . . . . . . . . . . . 9 6.2. Informative References . . . . . . . . . . . . . . . . . 9
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 10
A.1. Simple Query . . . . . . . . . . . . . . . . . . . . . . 10 A.1. Simple Query . . . . . . . . . . . . . . . . . . . . . . 10
A.2. Discovery of QUERY support . . . . . . . . . . . . . . . 10 A.2. Discovery of QUERY support . . . . . . . . . . . . . . . 11
A.3. Discovery of QUERY Formats . . . . . . . . . . . . . . . 11 A.3. Discovery of QUERY Formats . . . . . . . . . . . . . . . 11
A.4. Content-Location, Location, and Indirect Responses . . . 12 A.4. Content-Location, Location, and Indirect Responses . . . 12
A.4.1. Using Content-Location . . . . . . . . . . . . . . . 12 A.4.1. Using Content-Location . . . . . . . . . . . . . . . 13
A.4.2. Using Location . . . . . . . . . . . . . . . . . . . 13 A.4.2. Using Location . . . . . . . . . . . . . . . . . . . 14
A.4.3. Indirect Responses . . . . . . . . . . . . . . . . . 14 A.4.3. Indirect Responses . . . . . . . . . . . . . . . . . 14
A.5. More Query Formats . . . . . . . . . . . . . . . . . . . 14 A.5. More Query Formats . . . . . . . . . . . . . . . . . . . 15
Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 17 Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 18
B.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 17 B.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 18
B.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 18 B.2. Since draft-ietf-httpbis-safe-method-w-body-01 . . . . . 19
B.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 18 B.3. Since draft-ietf-httpbis-safe-method-w-body-02 . . . . . 19
B.4. Since draft-ietf-httpbis-safe-method-w-body-03 . . . . . 18 B.4. Since draft-ietf-httpbis-safe-method-w-body-03 . . . . . 19
B.5. Since draft-ietf-httpbis-safe-method-w-body-04 . . . . . 18 B.5. Since draft-ietf-httpbis-safe-method-w-body-04 . . . . . 19
B.6. Since draft-ietf-httpbis-safe-method-w-body-05 . . . . . 18 B.6. Since draft-ietf-httpbis-safe-method-w-body-05 . . . . . 19
B.7. Since draft-ietf-httpbis-safe-method-w-body-06 . . . . . 19 B.7. Since draft-ietf-httpbis-safe-method-w-body-06 . . . . . 20
B.8. Since draft-ietf-httpbis-safe-method-w-body-07 . . . . . 20 B.8. Since draft-ietf-httpbis-safe-method-w-body-07 . . . . . 21
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 B.9. Since draft-ietf-httpbis-safe-method-w-body-08 . . . . . 21
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 21
Contributors . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
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,
this is a common query pattern: this is a common query pattern:
skipping to change at page 6, line 38 skipping to change at page 6, line 44
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
differences, thereby improving cache efficiency, by: differences, thereby improving cache efficiency, by:
o Removing content encoding(s) o Removing content encoding(s) (Section 8.4 of [HTTP])
o Normalizing based upon knowledge of format conventions, as o Normalizing based upon knowledge of format conventions, as
indicated by any media type suffix in the request's Content-Type indicated by any media subtype suffix in the request's Content-
field (e.g., "+json") Type field (e.g., "+json", see Section 4.2.8 of [RFC6838])
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.
2.5. Range Requests 2.5. Range Requests
The semantics of Range Requests for QUERY are identical to those for The semantics of Range Requests for QUERY are identical to those for
skipping to change at page 9, line 49 skipping to change at page 10, line 7
[STRUCTURED-FIELDS] [STRUCTURED-FIELDS]
Nottingham, M. and P-H. Kamp, "Structured Field Values for Nottingham, M. and P-H. Kamp, "Structured Field Values for
HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024, HTTP", RFC 9651, DOI 10.17487/RFC9651, September 2024,
<https://www.rfc-editor.org/info/rfc9651>. <https://www.rfc-editor.org/info/rfc9651>.
6.2. Informative References 6.2. Informative References
[FETCH] WHATWG, "FETCH", <https://fetch.spec.whatwg.org>. [FETCH] WHATWG, "FETCH", <https://fetch.spec.whatwg.org>.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, DOI 10.17487/RFC6838, January 2013,
<https://www.rfc-editor.org/info/rfc6838>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>.
[RFC9535] Gössner, S., Ed., Normington, G., Ed., and C. Bormann, [RFC9535] Gössner, S., Ed., Normington, G., Ed., and C. Bormann,
Ed., "JSONPath: Query Expressions for JSON", RFC 9535, Ed., "JSONPath: Query Expressions for JSON", RFC 9535,
DOI 10.17487/RFC9535, February 2024, DOI 10.17487/RFC9535, February 2024,
<https://www.rfc-editor.org/info/rfc9535>. <https://www.rfc-editor.org/info/rfc9535>.
[URL] WHATWG, "URL", <https://url.spec.whatwg.org>.
[XSLT] Kay, M., "XSL Transformations (XSLT) Version 3.0", W3C [XSLT] Kay, M., "XSL Transformations (XSLT) Version 3.0", W3C
Recommendation REC-xslt-30-20170608, June 8, 2017, Recommendation REC-xslt-30-20170608, June 8, 2017,
<https://www.w3.org/TR/2017/REC-xslt-30-20170608/>. <https://www.w3.org/TR/2017/REC-xslt-30-20170608/>.
Latest version available at Latest version available at
<https://www.w3.org/TR/xslt-30/>. <https://www.w3.org/TR/xslt-30/>.
Appendix A. Examples Appendix A. Examples
The examples below are for illustrative purposes only; if one needs The examples below are for illustrative purposes only; if one needs
to send queries that are actually this short, it is probably better to send queries that are actually this short, it is probably better
to use GET. to use GET.
The media type used in most examples is "application/x-www-form- The media type used in most examples is "application/x-www-form-
urlencoded" (as used in POST requests from browser user clients). urlencoded" (as used in POST requests from browser user clients,
The Content-Length fields have been omitted for brevity. defined in "application/x-www-form-urlencoded
(https://url.spec.whatwg.org/#application/x-www-form-urlencoded)" in
[URL]). The Content-Length fields have been omitted for brevity.
A.1. Simple Query A.1. Simple Query
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: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
Accept: application/json Accept: application/json
skipping to change at page 14, line 34 skipping to change at page 15, line 19
See stored query at "/contacts/stored-queries/42". See stored query at "/contacts/stored-queries/42".
This is similar to including Location on a direct response, except This is similar to including Location on a direct response, except
that no result for the query is returned. This allows the server to that no result for the query is returned. This allows the server to
only generate an alternative resource. This resource could then be only generate an alternative resource. This resource could then be
used as shown in Appendix A.4.2. used as shown in Appendix A.4.2.
A.5. More Query Formats A.5. More Query Formats
The following examples show requests on a JSON-shaped database of RFC The following examples show requests on a JSON-shaped ([RFC8259])
errata. database of RFC errata.
The request below uses XSLT ([XSLT]) to extract errata information The request below uses XSLT ([XSLT]) to extract errata information
summarized per year and the defined errata types. summarized per year and the defined errata types.
QUERY /errata.json HTTP/1.1 QUERY /errata.json HTTP/1.1
Host: example.org Host: example.org
Content-Type: application/xslt+xml Content-Type: application/xslt+xml
Accept: application/xml, text/csv Accept: application/xml, text/csv
<transform xmlns="http://www.w3.org/1999/XSL/Transform" <transform xmlns="http://www.w3.org/1999/XSL/Transform"
skipping to change at page 20, line 13 skipping to change at page 21, line 13
extensions/issues/2957>) extensions/issues/2957>)
B.8. Since draft-ietf-httpbis-safe-method-w-body-07 B.8. Since draft-ietf-httpbis-safe-method-w-body-07
o Examples Section revised (<https://github.com/httpwg/http- o Examples Section revised (<https://github.com/httpwg/http-
extensions/issues/1906>) extensions/issues/1906>)
o Discuss Range Requests (<https://github.com/httpwg/http- o Discuss Range Requests (<https://github.com/httpwg/http-
extensions/issues/2979>) extensions/issues/2979>)
B.9. Since draft-ietf-httpbis-safe-method-w-body-08
o Add missing references, fixed terminology
(<https://github.com/httpwg/http-extensions/issues/3021>)
o Add Acknowledgements/Contributors sections; moved Ashok to
Contributors (<https://github.com/httpwg/http-extensions/
issues/3029>)
Acknowledgements
We thank all members of the HTTP Working Group for ideas, reviews,
and feedback.
The following individuals deserve special recognition: Carsten
Bormann, Mark Nottingham, Martin Thomson, Michael Thornburgh, Roberto
Polli, Roy Fielding, and Will Hawkins.
Contributors
Ashok Malhotra participated in early discussions leading to this
specification:
Ashok Malhotra
Email: malhotrasahib@gmail.com
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/
Ashok Malhotra
Email: malhotrasahib@gmail.com
James M Snell James M Snell
Email: jasnell@gmail.com Email: jasnell@gmail.com
Mike Bishop Mike Bishop
Akamai Akamai
Email: mbishop@evequefou.be Email: mbishop@evequefou.be
 End of changes. 19 change blocks. 
35 lines changed or deleted 73 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/