idnits 2.17.1 draft-ietf-httpbis-safe-method-w-body-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == There is 1 instance of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- -- The draft header indicates that this document updates RFC5323, but the abstract doesn't seem to directly say this. It does mention RFC5323 though, so this could be OK. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year (Using the creation date from RFC5323, updated by this document, for RFC5378 checks: 2002-03-26) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (8 June 2021) is 1051 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-19) exists of draft-ietf-httpbis-semantics-16 -- Possible downref: Normative reference to a draft: ref. 'RFCHTTP' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' -- Possible downref: Non-RFC (?) normative reference: ref. 'XMLNS' Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 HTTP J. Reschke 3 Internet-Draft greenbytes 4 Updates: 5323 (if approved) A. Malhotra 5 Intended status: Standards Track 6 Expires: 10 December 2021 J.M. Snell 7 8 June 2021 9 HTTP SEARCH Method 10 draft-ietf-httpbis-safe-method-w-body-01 12 Abstract 14 This specification updates the definition and semantics of the HTTP 15 SEARCH request method originally defined by RFC 5323. 17 Editorial Note 19 This note is to be removed before publishing as an RFC. 21 Discussion of this draft takes place on the HTTP working group 22 mailing list (ietf-http-wg@w3.org), which is archived at 23 https://lists.w3.org/Archives/Public/ietf-http-wg/. 25 Working Group information can be found at https://httpwg.org/; source 26 code and issues list for this draft can be found at 27 https://github.com/httpwg/http-extensions/labels/safe-method-w-body. 29 The changes in this draft are summarized in Appendix A.1. 31 Status of This Memo 33 This Internet-Draft is submitted in full conformance with the 34 provisions of BCP 78 and BCP 79. 36 Internet-Drafts are working documents of the Internet Engineering 37 Task Force (IETF). Note that other groups may also distribute 38 working documents as Internet-Drafts. The list of current Internet- 39 Drafts is at https://datatracker.ietf.org/drafts/current/. 41 Internet-Drafts are draft documents valid for a maximum of six months 42 and may be updated, replaced, or obsoleted by other documents at any 43 time. It is inappropriate to use Internet-Drafts as reference 44 material or to cite them other than as "work in progress." 46 This Internet-Draft will expire on 10 December 2021. 48 Copyright Notice 50 Copyright (c) 2021 IETF Trust and the persons identified as the 51 document authors. All rights reserved. 53 This document is subject to BCP 78 and the IETF Trust's Legal 54 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 55 license-info) in effect on the date of publication of this document. 56 Please review these documents carefully, as they describe your rights 57 and restrictions with respect to this document. Code Components 58 extracted from this document must include Simplified BSD License text 59 as described in Section 4.e of the Trust Legal Provisions and are 60 provided without warranty as described in the Simplified BSD License. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 65 2. SEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3. The "Accept-Search" Header Field . . . . . . . . . . . . . . 5 67 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 4.1. Simple SEARCH with a Direct Response . . . . . . . . . . 6 69 4.2. Simple SEARCH with indirect response (303 See Other) . . 6 70 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 71 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 72 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 73 Appendix A. Change Log . . . . . . . . . . . . . . . . . . . . . 8 74 A.1. Since draft-ietf-httpbis-safe-method-w-body-00 . . . . . 8 75 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9 77 1. Introduction 79 This specification updates the HTTP SEARCH method originally defined 80 in [RFC5323]. 82 Many existing HTTP-based applications use the HTTP GET and POST 83 methods in various ways to implement the functionality provided by 84 SEARCH. 86 Using a GET request with some combination of query parameters 87 included within the request URI (as illustrated in the example below) 88 is arguably the most common mechanism for implementing search in web 89 applications. With this approach, implementations are required to 90 parse the request URI into distinct path (everything before the '?') 91 and query elements (everything after the '?'). The path identifies 92 the resource processing the query (in this case 'http://example.org/ 93 feed') while the query identifies the specific parameters of the 94 search operation. 96 A typical use of HTTP GET for requesting a search 98 GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 99 Host: example.org 101 While there are definite advantages to using GET requests in this 102 manner, the disadvantages should not be overlooked. Specifically: 104 * Without specific knowledge of the resource and server to which the 105 GET request is being sent, there is no way for the client to know 106 that a search operation is being requested. Identical requests 107 sent to two different servers can implement entirely different 108 semantics. 110 * Encoding query parameters directly into the request URI 111 effectively casts every possible combination of query inputs as 112 distinct resources. For instance, because mechanisms such as HTTP 113 caching handle request URIs as opaque character sequences, queries 114 such as 'http://example.org/?q=foo' and 115 'http://example.org/?q=Foo' will be treated as entirely separate 116 resources even if they yield identical results. 118 * While most modern browser and server implementations allow for 119 long request URIs, there is no standardized minimum or maximum 120 length for URIs in general. Many resource constrained devices 121 enforce strict limits on the maximum number of characters that can 122 be included in a URI. Such limits can prove impractical for large 123 or complex query parameters. 125 * Query expressions included within a request URI must either be 126 restricted to relatively simple key value pairs or encoded such 127 that the query can be safely represented in the limited character- 128 set allowed by URL standards. Such encoding can add significant 129 complexity, introduce bugs, or otherwise reduce the overall 130 visibility of the query being requested. 132 As an alternative to using GET, many implementations make use of the 133 HTTP POST method to perform queries, as illustrated in the example 134 below. In this case, the input parameters to the search operation 135 are passed along within the request payload as opposed to using the 136 request URI. 138 A typical use of HTTP POST for requesting a search 139 POST /feed HTTP/1.1 140 Host: example.org 141 Content-Type: application/x-www-form-urlencoded 143 q=foo&limit=10&sort=-published 145 This variation, however, suffers from the same basic limitation as 146 GET in that it is not readily apparent -- absent specific knowledge 147 of the resource and server to which the request is being sent -- that 148 a search operation is what is being requested. Web applications use 149 the POST method for a wide variety of uses including the creation or 150 modification of existing resources. Sending the request above to a 151 different server, or even repeatedly sending the request to the same 152 server could have dramatically different effects. 154 The SEARCH method provides a solution that spans the gap between the 155 use of GET and POST. As with POST, the input to the query operation 156 is passed along within the payload of the request rather than as part 157 of the request URI. Unlike POST, however the semantics of the SEARCH 158 method are specifically defined. 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 162 "OPTIONAL" in this document are to be interpreted as described in BCP 163 14 [RFC2119] [RFC8174] when, and only when, they appear in all 164 capitals, as shown here. 166 2. SEARCH 168 The SEARCH method is used to initiate a server-side search. Unlike 169 the HTTP GET method, which requests that a server return a 170 representation of the resource identified by the target URI (as 171 defined by Section 7.1 of [RFCHTTP]), the SEARCH method is used to 172 ask the server to perform a query operation (described by the request 173 payload) over some set of data scoped to the effective request URI. 174 The payload returned in response to a SEARCH cannot be assumed to be 175 a representation of the resource identified by the effective request 176 URI. 178 The body payload of the request defines the query. Implementations 179 MAY use a request body of any content type with the SEARCH method; 180 however, for backwards compatibility with existing WebDAV 181 implementations, SEARCH requests that use the text/xml or 182 application/xml media types with a root element (Section 2.1 of 183 [XML]) in the "DAV:" XML namespace ([XMLNS]) MUST be processed per 184 the requirements established by [RFC5323]. 186 SEARCH requests are both safe and idempotent with regards to the 187 resource identified by the request URI. That is, SEARCH requests do 188 not alter the state of the targeted resource. However, while 189 processing a search request, a server can be expected to allocate 190 computing and memory resources or even create additional HTTP 191 resources through which the response can be retrieved. 193 A successful response to a SEARCH request is expected to provide some 194 indication as to the final disposition of the search operation. For 195 instance, a successful search that yields no results can be 196 represented by a 204 No Content response. If the response includes a 197 content, it is expected to describe the results of the search 198 operation. In some cases, the server may choose to respond 199 indirectly to the SEARCH request by returning a 3xx Redirection with 200 a Location header field specifying an alternate Request URI from 201 which the search results can be retrieved using an HTTP GET request. 202 Various non-normative examples of successful SEARCH responses are 203 illustrated in Section 4. 205 The response to a SEARCH request is not cacheable. It ought to be 206 noted, however, that because SEARCH requests are safe and idempotent, 207 responses to a SEARCH MUST NOT invalidate previously cached responses 208 to other requests directed at the same effective request URI. 209 // By default, that is. We need to figure out under which conditions 210 // we can make the result cacheable. 212 The semantics of the SEARCH method change to a "conditional SEARCH" 213 if the request message includes an If-Modified-Since, If-Unmodified- 214 Since, If-Match, If-None-Match, or If-Range header field ([RFCHTTP], 215 Section 13). A conditional SEARCH requests that the query be 216 performed only under the circumstances described by the conditional 217 header field(s). It is important to note, however, that such 218 conditions are evaluated against the state of the target resource 219 itself as opposed to the collected results of the search operation. 221 3. The "Accept-Search" Header Field 223 The "Accept-Search" response header field MAY be used by a server to 224 directly signal support for the SEARCH method while identifying the 225 specific query format media types that may be used. 227 Accept-Search = 1#media-type 229 The Accept-Search header field specifies a comma-separated listing of 230 media types (with optional parameters) as defined by Section 8.3.1 of 231 [RFCHTTP]. 233 The order of types listed by the Accept-Search header field is 234 insignificant. 236 4. Examples 238 The non-normative examples in this section make use of a simple, 239 hypothetical plain-text based query syntax based on SQL with results 240 returned as comma-separated values. This is done for illustration 241 purposes only. Implementations are free to use any format they wish 242 on both the request and response. 244 4.1. Simple SEARCH with a Direct Response 246 A simple query with a direct response: 248 SEARCH /contacts HTTP/1.1 249 Host: example.org 250 Content-Type: example/query 251 Accept: text/csv 253 select surname, givenname, email limit 10 255 Response: 257 HTTP/1.1 200 OK 258 Content-Type: text/csv 260 surname, givenname, email 261 Smith, John, john.smith@example.org 262 Jones, Sally, sally.jones@example.com 263 Dubois, Camille, camille.dubois@example.net 265 4.2. Simple SEARCH with indirect response (303 See Other) 267 A simple query with an Indirect Response (303 See Other): 269 SEARCH /contacts HTTP/1.1 270 Host: example.org 271 Content-Type: example/query 272 Accept: text/csv 274 select surname, givenname, email limit 10 276 Response: 278 HTTP/1.1 303 See Other 279 Location: http://example.org/contacts/query123 280 Fetch Query Response: 282 GET /contacts/query123 HTTP/1.1 283 Host: example.org 285 Response: 287 HTTP/1.1 200 OK 288 Content-Type: text/csv 290 surname, givenname, email 291 Smith, John, john.smith@example.org 292 Jones, Sally, sally.jones@example.com 293 Dubois, Camille, camille.dubois@example.net 295 5. Security Considerations 297 The SEARCH method is subject to the same general security 298 considerations as all HTTP methods as described in [RFCHTTP]. 300 6. IANA Considerations 302 IANA is requested to update the registration of the SEARCH method in 303 the permanent registry at (see Section 16.1.1 of [RFCHTTP]). 306 +=============+======+============+===============+ 307 | Method Name | Safe | Idempotent | Specification | 308 +=============+======+============+===============+ 309 | SEARCH | Yes | Yes | Section 2 | 310 +-------------+------+------------+---------------+ 312 Table 1 314 7. Normative References 316 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 317 Requirement Levels", BCP 14, RFC 2119, 318 DOI 10.17487/RFC2119, March 1997, 319 . 321 [RFC5323] Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich, 322 "Web Distributed Authoring and Versioning (WebDAV) 323 SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008, 324 . 326 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 327 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 328 May 2017, . 330 [RFCHTTP] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 331 Ed., "HTTP Semantics", Work in Progress, Internet-Draft, 332 draft-ietf-httpbis-semantics-16, 27 May 2021, 333 . 336 [XML] Bray, T., Paoli, J., Sperberg-McQueen, M., Maler, E., and 337 F. Yergeau, "Extensible Markup Language (XML) 1.0 (Fifth 338 Edition)", W3C Recommendation REC-xml-20081126, 26 339 November 2008, 340 . Latest 341 version available at https://www.w3.org/TR/xml/. 343 [XMLNS] Bray, T., Hollander, D., Layman, A., Tobin, R., and H. 344 Thompson, "Namespaces in XML 1.0 (Third Edition)", W3C 345 Recommendation REC-xml-names-20091208, 8 December 2009, 346 . 347 Latest version available at https://www.w3.org/TR/xml- 348 names/. 350 Appendix A. Change Log 352 This section is to be removed before publishing as an RFC. 354 // (see https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/622) 356 A.1. Since draft-ietf-httpbis-safe-method-w-body-00 358 * Use "example/query" media type instead of undefined "text/query" 359 (https://github.com/httpwg/http-extensions/issues/1450) 361 * In Section 3, adjust the grammar to just define the field value 362 (https://github.com/httpwg/http-extensions/issues/1470) 364 * Update to latest HTTP core spec, and adjust terminology 365 accordingly (https://github.com/httpwg/http-extensions/ 366 issues/1473) 368 * Reference RFC 8174 and markup bcp14 terms 369 (https://github.com/httpwg/http-extensions/issues/1497) 371 * Update HTTP reference (https://github.com/httpwg/http-extensions/ 372 issues/1524) 374 * Relax restriction of generic XML media type in request body 375 (https://github.com/httpwg/http-extensions/issues/1535) 377 Authors' Addresses 379 Julian Reschke 380 greenbytes GmbH 381 Hafenweg 16 382 48155 Münster 383 Germany 385 Email: julian.reschke@greenbytes.de 386 URI: https://greenbytes.de/tech/webdav/ 388 Ashok Malhotra 390 Email: malhotrasahib@gmail.com 392 James M Snell 394 Email: jasnell@gmail.com