idnits 2.17.1 draft-ietf-httpbis-safe-method-w-body-00.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 == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). (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 (31 March 2021) is 1121 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) ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7232 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 3 warnings (==), 3 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: 2 October 2021 J.M. Snell 7 31 March 2021 9 HTTP SEARCH Method 10 draft-ietf-httpbis-safe-method-w-body-00 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 Discussion of this draft takes place on the HTTP working group 20 mailing list (ietf-http-wg@w3.org), which is archived at 21 https://lists.w3.org/Archives/Public/ietf-http-wg/. 23 This note is to be removed before publishing as an RFC. 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 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at https://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on 2 October 2021. 46 Copyright Notice 48 Copyright (c) 2021 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 53 license-info) in effect on the date of publication of this document. 54 Please review these documents carefully, as they describe your rights 55 and restrictions with respect to this document. Code Components 56 extracted from this document must include Simplified BSD License text 57 as described in Section 4.e of the Trust Legal Provisions and are 58 provided without warranty as described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 63 2. SEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. The "Accept-Search" Header Field . . . . . . . . . . . . . . 5 65 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 4.1. Simple SEARCH with a Direct Response . . . . . . . . . . 6 67 4.2. Simple SEARCH with indirect response (303 See Other) . . 6 68 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 69 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 70 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 71 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 73 1. Introduction 75 This specification updates the HTTP SEARCH method originally defined 76 in [RFC5323]. 78 Many existing HTTP-based applications use the HTTP GET and POST 79 methods in various ways to implement the functionality provided by 80 SEARCH. 82 Using a GET request with some combination of query parameters 83 included within the request URI (as illustrated in the example below) 84 is arguably the most common mechanism for implementing search in web 85 applications. With this approach, implementations are required to 86 parse the request URI into distinct path (everything before the '?') 87 and query elements (everything after the '?'). The path identifies 88 the resource processing the query (in this case 'http://example.org/ 89 feed') while the query identifies the specific parameters of the 90 search operation. 92 A typical use of HTTP GET for requesting a search 93 GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 94 Host: example.org 96 While there are definite advantages to using GET requests in this 97 manner, the disadvantages should not be overlooked. Specifically: 99 * Without specific knowledge of the resource and server to which the 100 GET request is being sent, there is no way for the client to know 101 that a search operation is being requested. Identical requests 102 sent to two different servers can implement entirely different 103 semantics. 105 * Encoding query parameters directly into the request URI 106 effectively casts every possible combination of query inputs as 107 distinct resources. For instance, because mechanisms such as HTTP 108 caching handle request URIs as opaque character sequences, queries 109 such as 'http://example.org/?q=foo' and 110 'http://example.org/?q=Foo' will be treated as entirely separate 111 resources even if they yield identical results. 113 * While most modern browser and server implementations allow for 114 long request URIs, there is no standardized minimum or maximum 115 length for URIs in general. Many resource constrained devices 116 enforce strict limits on the maximum number of characters that can 117 be included in a URI. Such limits can prove impractical for large 118 or complex query parameters. 120 * Query expressions included within a request URI must either be 121 restricted to relatively simple key value pairs or encoded such 122 that the query can be safely represented in the limited character- 123 set allowed by URL standards. Such encoding can add significant 124 complexity, introduce bugs, or otherwise reduce the overall 125 visibility of the query being requested. 127 As an alternative to using GET, many implementations make use of the 128 HTTP POST method to perform queries, as illustrated in the example 129 below. In this case, the input parameters to the search operation 130 are passed along within the request payload as opposed to using the 131 request URI. 133 A typical use of HTTP POST for requesting a search 135 POST /feed HTTP/1.1 136 Host: example.org 137 Content-Type: application/x-www-form-urlencoded 139 q=foo&limit=10&sort=-published 140 This variation, however, suffers from the same basic limitation as 141 GET in that it is not readily apparent -- absent specific knowledge 142 of the resource and server to which the request is being sent -- that 143 a search operation is what is being requested. Web applications use 144 the POST method for a wide variety of uses including the creation or 145 modification of existing resources. Sending the request above to a 146 different server, or even repeatedly sending the request to the same 147 server could have dramatically different effects. 149 The SEARCH method provides a solution that spans the gap between the 150 use of GET and POST. As with POST, the input to the query operation 151 is passed along within the payload of the request rather than as part 152 of the request URI. Unlike POST, however the semantics of the SEARCH 153 method are specifically defined. 155 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 156 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 157 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 159 2. SEARCH 161 The SEARCH method is used to initiate a server-side search. Unlike 162 the HTTP GET method, which requests that a server return a 163 representation of the resource identified by the effective request 164 URI (as defined by [RFC7230]), the SEARCH method is used to ask the 165 server to perform a query operation (described by the request 166 payload) over some set of data scoped to the effective request URI. 167 The payload returned in response to a SEARCH cannot be assumed to be 168 a representation of the resource identified by the effective request 169 URI. 171 The body payload of the request defines the query. Implementations 172 MAY use a request body of any content type with the SEARCH method; 173 however, for backwards compatibility with existing WebDAV 174 implementations, SEARCH requests that use the text/xml or 175 application/xml content types MUST be processed per the requirements 176 established by [RFC5323]. 177 // This can be relaxed to XML with a document element in the "DAV:" 178 // namespace, or even to the two element names mentionbed in 179 // Section 2.2.2 of [RFC5323]. 181 SEARCH requests are both safe and idempotent with regards to the 182 resource identified by the request URI. That is, SEARCH requests do 183 not alter the state of the targeted resource. However, while 184 processing a search request, a server can be expected to allocate 185 computing and memory resources or even create additional HTTP 186 resources through which the response can be retrieved. 188 A successful response to a SEARCH request is expected to provide some 189 indication as to the final disposition of the search operation. For 190 instance, a successful search that yields no results can be 191 represented by a 204 No Content response. If the response includes a 192 body payload, the payload is expected to describe the results of the 193 search operation. In some cases, the server may choose to respond 194 indirectly to the SEARCH request by returning a 3xx Redirection with 195 a Location header specifying an alternate Request URI from which the 196 search results can be retrieved using an HTTP GET request. Various 197 non-normative examples of successful SEARCH responses are illustrated 198 in Section 4. 200 The response to a SEARCH request is not cacheable. It ought to be 201 noted, however, that because SEARCH requests are safe and idempotent, 202 responses to a SEARCH MUST NOT invalidate previously cached responses 203 to other requests directed at the same effective request URI. 204 // By default, that is. We need to figure out under which conditions 205 // we can make the result cacheable. 207 The semantics of the SEARCH method change to a "conditional SEARCH" 208 if the request message includes an If-Modified-Since, If-Unmodified- 209 Since, If-Match, If-None-Match, or If-Range header field ([RFC7232]). 210 A conditional SEARCH requests that the query be performed only under 211 the circumstances described by the conditional header field(s). It 212 is important to note, however, that such conditions are evaluated 213 against the state of the target resource itself as opposed to the 214 collected results of the search operation. 216 3. The "Accept-Search" Header Field 218 The "Accept-Search" response header field MAY be used by a server to 219 directly signal support for the SEARCH method while identifying the 220 specific query format Content-Type's that may be used. 222 Accept-Search = "Accept-Search" ":" 1#media-type 224 The Accept-Search header specifies a comma-separated listing of media 225 types (with optional parameters) as defined by [RFC7231], 226 Section 3.1.1.1. 228 The order of types listed by the Accept-Search header is 229 insignificant. 231 4. Examples 233 The non-normative examples in this section make use of a simple, 234 hypothetical plain-text based query syntax based on SQL with results 235 returned as comma-separated values. This is done for illustration 236 purposes only. Implementations are free to use any format they wish 237 on both the request and response. 239 4.1. Simple SEARCH with a Direct Response 241 A simple query with a direct response: 243 SEARCH /contacts HTTP/1.1 244 Host: example.org 245 Content-Type: text/query 246 Accept: text/csv 248 select surname, givenname, email limit 10 250 Response: 252 HTTP/1.1 200 OK 253 Content-Type: text/csv 255 surname, givenname, email 256 Smith, John, john.smith@example.org 257 Jones, Sally, sally.jones@example.com 258 Dubois, Camille, camille.dubois@example.net 260 4.2. Simple SEARCH with indirect response (303 See Other) 262 A simple query with an Indirect Response (303 See Other): 264 SEARCH /contacts HTTP/1.1 265 Host: example.org 266 Content-Type: text/query 267 Accept: text/csv 269 select surname, givenname, email limit 10 271 Response: 273 HTTP/1.1 303 See Other 274 Location: http://example.org/contacts/query123 276 Fetch Query Response: 278 GET /contacts/query123 HTTP/1.1 279 Host: example.org 281 Response: 283 HTTP/1.1 200 OK 284 Content-Type: text/csv 286 surname, givenname, email 287 Smith, John, john.smith@example.org 288 Jones, Sally, sally.jones@example.com 289 Dubois, Camille, camille.dubois@example.net 291 5. Security Considerations 293 The SEARCH method is subject to the same general security 294 considerations as all HTTP methods as described in [RFC7231]. 296 6. IANA Considerations 298 IANA is requested to update the registration of the SEARCH method in 299 the permanent registry at (see Section 8.1 of [RFC7231]). 302 +=============+======+============+===============+ 303 | Method Name | Safe | Idempotent | Specification | 304 +=============+======+============+===============+ 305 | SEARCH | Yes | Yes | Section 2 | 306 +-------------+------+------------+---------------+ 308 Table 1 310 7. Normative References 312 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 313 Requirement Levels", BCP 14, RFC 2119, 314 DOI 10.17487/RFC2119, March 1997, 315 . 317 [RFC5323] Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich, 318 "Web Distributed Authoring and Versioning (WebDAV) 319 SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008, 320 . 322 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 323 Protocol (HTTP/1.1): Message Syntax and Routing", 324 RFC 7230, DOI 10.17487/RFC7230, June 2014, 325 . 327 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 328 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 329 DOI 10.17487/RFC7231, June 2014, 330 . 332 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 333 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 334 DOI 10.17487/RFC7232, June 2014, 335 . 337 Authors' Addresses 339 Julian Reschke 340 greenbytes GmbH 341 Hafenweg 16 342 48155 Münster 343 Germany 345 Email: julian.reschke@greenbytes.de 346 URI: https://greenbytes.de/tech/webdav/ 348 Ashok Malhotra 350 Email: malhotrasahib@gmail.com 352 James M Snell 354 Email: jasnell@gmail.com