idnits 2.17.1 draft-snell-search-method-02.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 (September 2, 2020) is 1304 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 Network Working Group J. Reschke 3 Internet-Draft greenbytes 4 Updates: 5323 (if approved) A. Malhotra 5 Intended status: Standards Track 6 Expires: March 6, 2021 J.M. Snell 7 September 2, 2020 9 HTTP SEARCH Method 10 draft-snell-search-method-02 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 Distribution of this document is unlimited. Although this is not a 22 work item of the HTTPbis Working Group, comments should be sent to 23 the Hypertext Transfer Protocol (HTTP) mailing list at ietf-http- 24 wg@w3.org (mailto:ietf-http-wg@w3.org), which may be joined by 25 sending a message with subject "subscribe" to ietf-http-wg- 26 request@w3.org (mailto:ietf-http-wg- 27 request@w3.org?subject=subscribe). 29 Discussions of the HTTPbis Working Group are archived at 30 . 32 Status of This Memo 34 This Internet-Draft is submitted in full conformance with the 35 provisions of BCP 78 and BCP 79. 37 Internet-Drafts are working documents of the Internet Engineering 38 Task Force (IETF). Note that other groups may also distribute 39 working documents as Internet-Drafts. The list of current Internet- 40 Drafts is at https://datatracker.ietf.org/drafts/current/. 42 Internet-Drafts are draft documents valid for a maximum of six months 43 and may be updated, replaced, or obsoleted by other documents at any 44 time. It is inappropriate to use Internet-Drafts as reference 45 material or to cite them other than as "work in progress." 47 This Internet-Draft will expire on March 6, 2021. 49 Copyright Notice 51 Copyright (c) 2020 IETF Trust and the persons identified as the 52 document authors. All rights reserved. 54 This document is subject to BCP 78 and the IETF Trust's Legal 55 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 56 license-info) in effect on the date of publication of this document. 57 Please review these documents carefully, as they describe your rights 58 and restrictions with respect to this document. Code Components 59 extracted from this document must include Simplified BSD License text 60 as described in Section 4.e of the Trust Legal Provisions and are 61 provided without warranty as described in the Simplified BSD License. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 66 2. SEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. The "Accept-Search" Header Field . . . . . . . . . . . . . . 5 68 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5 69 4.1. Simple SEARCH with a Direct Response . . . . . . . . . . 6 70 4.2. Simple SEARCH with indirect response (303 See Other) . . 6 71 5. Security Considerations . . . . . . . . . . . . . . . . . . . 7 72 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 73 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 76 1. Introduction 78 This specification updates the HTTP SEARCH method originally defined 79 in [RFC5323]. 81 Many existing HTTP-based applications use the HTTP GET and POST 82 methods in various ways to implement the functionality provided by 83 SEARCH. 85 Using a GET request with some combination of query parameters 86 included within the request URI (as illustrated in the example below) 87 is arguably the most common mechanism for implementing search in web 88 applications. With this approach, implementations are required to 89 parse the request URI into distinct path (everything before the '?') 90 and query elements (everything after the '?'). The path identifies 91 the resource processing the query (in this case 'http://example.org/ 92 feed') while the query identifies the specific parameters of the 93 search operation. 95 A typical use of HTTP GET for requesting a search 96 GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 97 Host: example.org 99 While there are definite advantages to using GET requests in this 100 manner, the disadvantages should not be overlooked. Specifically: 102 o Without specific knowledge of the resource and server to which the 103 GET request is being sent, there is no way for the client to know 104 that a search operation is being requested. Identical requests 105 sent to two different servers can implement entirely different 106 semantics. 108 o Encoding query parameters directly into the request URI 109 effectively casts every possible combination of query inputs as 110 distinct resources. For instance, because mechanisms such as HTTP 111 caching handle request URIs as opaque character sequences, queries 112 such as 'http://example.org/?q=foo' and 113 'http://example.org/?q=Foo' will be treated as entirely separate 114 resources even if they yield identical results. 116 o While most modern browser and server implementations allow for 117 long request URIs, there is no standardized minimum or maximum 118 length for URIs in general. Many resource constrained devices 119 enforce strict limits on the maximum number of characters that can 120 be included in a URI. Such limits can prove impractical for large 121 or complex query parameters. 123 o Query expressions included within a request URI must either be 124 restricted to relatively simple key value pairs or encoded such 125 that the query can be safely represented in the limited character- 126 set allowed by URL standards. Such encoding can add significant 127 complexity, introduce bugs, or otherwise reduce the overall 128 visibility of the query being requested. 130 As an alternative to using GET, many implementations make use of the 131 HTTP POST method to perform queries, as illustrated in the example 132 below. In this case, the input parameters to the search operation 133 are passed along within the request payload as opposed to using the 134 request URI. 136 A typical use of HTTP GET for requesting a search 138 POST /feed HTTP/1.1 139 Host: example.org 140 Content-Type: application/x-www-form-urlencoded 142 q=foo&limit=10&sort=-published 143 This variation, however, suffers from the same basic limitation as 144 GET in that it is not readily apparent -- absent specific knowledge 145 of the resource and server to which the request is being sent -- that 146 a search operation is what is being requested. Web applications use 147 the POST method for a wide variety of uses including the creation or 148 modification of existing resources. Sending the request above to a 149 different server, or even repeatedly sending the request to the same 150 server could have dramatically different effects. 152 The SEARCH method provides a solution that spans the gap between the 153 use of GET and POST. As with POST, the input to the query operation 154 is passed along within the payload of the request rather than as part 155 of the request URI. Unlike POST, however the semantics of the SEARCH 156 method are specifically defined. 158 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 159 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 160 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 162 2. SEARCH 164 The SEARCH method is used to initiate a server-side search. Unlike 165 the HTTP GET method, which requests that a server return a 166 representation of the resource identified by the effective request 167 URI (as defined by [RFC7230]), the SEARCH method is used to ask the 168 server to perform a query operation (described by the request 169 payload) over some set of data scoped to the effective request URI. 170 The payload returned in response to a SEARCH cannot be assumed to be 171 a representation of the resource identified by the effective request 172 URI. 174 The body payload of the request defines the query. Implementations 175 MAY use a request body of any content type with the SEARCH method; 176 however, for backwards compatibility with existing WebDAV 177 implementations, SEARCH requests that use the text/xml or 178 application/xml content types MUST be processed per the requirements 179 established by [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. 205 The semantics of the SEARCH method change to a "conditional SEARCH" 206 if the request message includes an If-Modified-Since, If-Unmodified- 207 Since, If-Match, If-None-Match, or If-Range header field ([RFC7232]). 208 A conditional SEARCH requests that the query be performed only under 209 the circumstances described by the conditional header field(s). It 210 is important to note, however, that such conditions are evaluated 211 against the state of the target resource itself as opposed to the 212 collected results of the search operation. 214 3. The "Accept-Search" Header Field 216 The "Accept-Search" response header field MAY be used by a server to 217 directly signal support for the SEARCH method while identifying the 218 specific query format Content-Type's that may be used. 220 Accept-Search = "Accept-Search" ":" 1#media-type 222 The Accept-Search header specifies a comma-separated listing of media 223 types (with optional parameters) as defined by [RFC7231], 224 Section 3.1.1.1. 226 The order of types listed by the Accept-Search header is 227 insignificant. 229 4. Examples 231 The non-normative examples in this section make use of a simple, 232 hypothetical plain-text based query syntax based on SQL with results 233 returned as comma-separated values. This is done for illustration 234 purposes only. Implementations are free to use any format they wish 235 on both the request and response. 237 4.1. Simple SEARCH with a Direct Response 239 A simple query with a direct response: 241 SEARCH /contacts HTTP/1.1 242 Host: example.org 243 Content-Type: text/query 244 Accept: text/csv 246 select surname, givenname, email limit 10 248 Response: 250 HTTP/1.1 200 OK 251 Content-Type: text/csv 253 surname, givenname, email 254 Smith, John, john.smith@example.org 255 Jones, Sally, sally.jones@example.com 256 Dubois, Camille, camille.dubois@example.net 258 4.2. Simple SEARCH with indirect response (303 See Other) 260 A simple query with an Indirect Response (303 See Other) 262 SEARCH /contacts HTTP/1.1 263 Host: example.org 264 Content-Type: text/query 265 Accept: text/csv 267 select surname, givenname, email limit 10 269 Response: 271 HTTP/1.1 303 See Other 272 Location: http://example.org/contacts/query123 274 Fetch Query Response: 276 GET /contacts/query123 HTTP/1.1 277 Host: example.org 279 Response: 281 HTTP/1.1 200 OK 282 Content-Type: text/csv 284 surname, givenname, email 285 Smith, John, john.smith@example.org 286 Jones, Sally, sally.jones@example.com 287 Dubois, Camille, camille.dubois@example.net 289 5. Security Considerations 291 The SEARCH method is subject to the same general security 292 considerations as all HTTP methods as described in [RFC7231]. 294 6. IANA Considerations 296 IANA is requested to update the registration of the SEARCH method in 297 the permanent registry at (see Section 8.1 of [RFC7231]). 300 +-------------+------+------------+---------------+ 301 | Method Name | Safe | Idempotent | Specification | 302 +-------------+------+------------+---------------+ 303 | SEARCH | Yes | Yes | Section 2 | 304 +-------------+------+------------+---------------+ 306 Table 1 308 7. Normative References 310 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 311 Requirement Levels", BCP 14, RFC 2119, 312 DOI 10.17487/RFC2119, March 1997, 313 . 315 [RFC5323] Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich, 316 "Web Distributed Authoring and Versioning (WebDAV) 317 SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008, 318 . 320 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 321 Protocol (HTTP/1.1): Message Syntax and Routing", 322 RFC 7230, DOI 10.17487/RFC7230, June 2014, 323 . 325 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 326 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 327 DOI 10.17487/RFC7231, June 2014, 328 . 330 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 331 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 332 DOI 10.17487/RFC7232, June 2014, 333 . 335 Authors' Addresses 337 Julian Reschke 338 greenbytes GmbH 339 Hafenweg 16 340 48155 Münster 341 Germany 343 Email: julian.reschke@greenbytes.de 344 URI: https://greenbytes.de/tech/webdav/ 346 Ashok Malhotra 348 Email: malhotrasahib@gmail.com 350 James M Snell 352 Email: jasnell@gmail.com