idnits 2.17.1 draft-snell-search-method-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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC5323]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. 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). -- The document date (September 19, 2018) is 2043 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) == Unused Reference: 'RFC4918' is defined on line 298, but no explicit reference was found in the text == Unused Reference: 'RFC7234' is defined on line 323, but no explicit reference was found in the text ** 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) ** Obsolete normative reference: RFC 7234 (Obsoleted by RFC 9111) Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Individual Submission J. Reschke 3 Internet-Draft 4 Intended status: Standards Track A. Malhotra 5 Expires: March 23, 2019 6 J. Snell 7 September 19, 2018 9 HTTP SEARCH Method 10 draft-snell-search-method-01 12 Abstract 14 This specification updates the definition and semantics of the HTTP 15 SEARCH request method originally defined by [RFC5323]. 17 Status of This Memo 19 This Internet-Draft is submitted to IETF in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on March 23, 2019. 34 Copyright Notice 36 Copyright (c) 2018 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents 41 (https://trustee.ietf.org/license-info) in effect on the date of 42 publication of this document. Please review these documents 43 carefully, as they describe your rights and restrictions with respect 44 to this document. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 49 2. SEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 50 3. The "Accept-Search" Header Field . . . . . . . . . . . . . . 5 51 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5 52 4.1. Simple SEARCH with a Direct Response . . . . . . . . . . 5 53 4.2. Simple SEARCH with indirect response (303 See Other) . . 6 54 5. Security Considerations . . . . . . . . . . . . . . . . . . . 6 55 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 56 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 57 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 59 1. Introduction 61 This specification updates the HTTP SEARCH method originally defined 62 in [RFC5323]. 64 Many existing HTTP-based applications use the HTTP GET and POST 65 methods in various ways to implement the functionality provided by 66 SEARCH. 68 Using a GET request with some combination of query parameters 69 included within the request URI (as illustrated in the example below) 70 is arguably the most common mechanism for implementing search in web 71 applications. With this approach, implementations are required to 72 parse the request URI into distinct path (everything before the '?') 73 and query elements (everything after the '?'). The path identifies 74 the resource processing the query (in this case 'http://example.org/ 75 feed') while the query identifies the specific parameters of the 76 search operation. 78 A typical use of HTTP GET for requesting a search 80 GET /feed?q=foo&limit=10&sort=-published HTTP/1.1 81 Host: example.org 83 While there are definite advantages to using GET requests in this 84 manner, the disadvantages should not be overlooked. Specifically: 86 o Without specific knowledge of the resource and server to which the 87 GET request is being sent, there is no way for the client to know 88 that a search operation is being requested. Identical requests 89 sent to two different servers can implement entirely different 90 semantics. 92 o Encoding query parameters directly into the request URI 93 effectively casts every possible combination of query inputs as 94 distinct resources. For instance, because mechanisms such as HTTP 95 caching handle request URIs as opaque character sequences, queries 96 such as 'http://example.org/?q=foo' and 97 'http://example.org/?q=Foo' will be treated as entirely separate 98 resources even if they yield identical results. 100 o While most modern browser and server implementations allow for 101 long request URIs, there is no standardized minimum or maximum 102 length for URIs in general. Many resource constrained devices 103 enforce strict limits on the maximum number of characters that can 104 be included in a URI. Such limits can prove impractical for large 105 or complex query parameters. 107 o Query expressions included within a request URI must either be 108 restricted to relatively simple key value pairs or encoded such 109 that the query can be safely represented in the limited character- 110 set allowed by URL standards. Such encoding can add significant 111 complexity, introduce bugs, or otherwise reduce the overall 112 visibility of the query being requested. 114 As an alternative to using GET, many implementations make use of the 115 HTTP POST method to perform queries, as illustrated in the example 116 below. In this case, the input parameters to the search operation 117 are passed along within the request payload as opposed to using the 118 request URI. 120 A typical use of HTTP GET for requesting a search 122 POST /feed HTTP/1.1 123 Host: example.org 124 Content-Type: application/x-www-form-urlencoded 126 q=foo&limit=10&sort=-published 128 This variation, however, suffers from the same basic limitation as 129 GET in that it is not readily apparent -- absent specific knowledge 130 of the resource and server to which the request is being sent -- that 131 a search operation is what is being requested. Web applications use 132 the POST method for a wide variety of uses including the creation or 133 modification of existing resources. Sending the request above to a 134 different server, or even repeatedly sending the request to the same 135 server could have dramatically different effects. 137 The SEARCH method provides a solution that spans the gap between the 138 use of GET and POST. As with POST, the input to the query operation 139 is passed along within the payload of the request rather than as part 140 of the request URI. Unlike POST, however the semantics of the SEARCH 141 method are specifically defined. 143 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 144 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 145 and "OPTIONAL" are to be interpreted as described in [RFC2119]. 147 2. SEARCH 149 The SEARCH method is used to initiate a server-side search. Unlike 150 the HTTP GET method, which requests that a server return a 151 representation of the resource identified by the effective request 152 URI (as defined by [RFC7230]), the SEARCH method is used to ask the 153 server to perform a query operation (described by the request 154 payload) over some set of data scoped to the effective request URI. 155 The payload returned in response to a SEARCH cannot be assumed to be 156 a representation of the resource identified by the effective request 157 URI. 159 The body payload of the request defines the query. Implementations 160 MAY use a request body of any content type with the SEARCH method; 161 however, for backwards compatibility with existing WebDAV 162 implementations, SEARCH requests that use the text/xml or 163 application/xml content types MUST be processed per the requirements 164 established by [RFC5323]. 166 SEARCH requests are both safe and idempotent with regards to the 167 resource identified by the request URI. That is, SEARCH requests do 168 not alter the state of the targeted resource. However, while 169 processing a search request, a server can be expected to allocate 170 computing and memory resources or even create additional HTTP 171 resources through which the response can be retrieved. 173 A successful response to a SEARCH request is expected to provide some 174 indication as to the final disposition of the search operation. For 175 instance, a successful search that yields no results can be 176 represented by a 204 No Content response. If the response includes a 177 body payload, the payload is expected to describe the results of the 178 search operation. In some cases, the server may choose to respond 179 indirectly to the SEARCH request by returning a 3xx Redirection with 180 a Location header specifying an alternate Request URI from which the 181 search results can be retrieved using an HTTP GET request. Various 182 non-normative examples of successful SEARCH responses are illustrated 183 in Section 4. 185 The response to a SEARCH request is not cacheable. It ought to be 186 noted, however, that because SEARCH requests are safe and idempotent, 187 responses to a SEARCH MUST NOT invalidate previously cached responses 188 to other requests directed at the same effective request URI. 190 The semantics of the SEARCH method change to a "conditional SEARCH" 191 if the request message includes an If-Modified-Since, If-Unmodified- 192 Since, If-Match, If-None-Match, or If-Range header field ([RFC7232]). 193 A conditional SEARCH requests that the query be performed only under 194 the circumstances described by the conditional header field(s). It 195 is important to note, however, that such conditions are evaluated 196 against the state of the target resource itself as opposed to the 197 collected results of the search operation. 199 3. The "Accept-Search" Header Field 201 The "Accept-Search" response header field MAY be used by a server to 202 directly signal support for the SEARCH method while identifying the 203 specific query format Content-Type's that may be used. 205 Accept-Search = "Accept-Search" ":" 1#media-type 207 The Accept-Search header specifies a comma-separated listing of media 208 types (with optional parameters) as defined by [RFC7231], 209 Section 3.1.1.1. 211 The order of types listed by the Accept-Search header is 212 insignificant. 214 4. Examples 216 The non-normative examples in this section make use of a simple, 217 hypothetical plain-text based query syntax based on SQL with results 218 returned as comma-separated values. This is done for illustration 219 purposes only. Implementations are free to use any format they wish 220 on both the request and response. 222 4.1. Simple SEARCH with a Direct Response 224 A simple query with a direct response: 226 SEARCH /contacts HTTP/1.1 227 Host: example.org 228 Content-Type: text/query 229 Accept: text/csv 231 select surname, givenname, email limit 10 233 Response: 235 HTTP/1.1 200 OK 236 Content-Type: text/csv 238 surname, givenname, email 239 Smith, John, john.smith@example.org 240 Jones, Sally, sally.jones@example.com 241 Dubois, Camille, camille.dubois@example.net 243 4.2. Simple SEARCH with indirect response (303 See Other) 245 A simple query with an Indirect Response (303 See Other) 247 SEARCH /contacts HTTP/1.1 248 Host: example.org 249 Content-Type: text/query 250 Accept: text/csv 252 select surname, givenname, email limit 10 254 Response: 256 HTTP/1.1 303 See Other 257 Location: http://example.org/contacts/query123 259 Fetch Query Response: 261 GET /contacts/query123 HTTP/1.1 262 Host: example.org 264 Response: 266 HTTP/1.1 200 OK 267 Content-Type: text/csv 269 surname, givenname, email 270 Smith, John, john.smith@example.org 271 Jones, Sally, sally.jones@example.com 272 Dubois, Camille, camille.dubois@example.net 274 5. Security Considerations 276 The SEARCH method is subject to the same general security 277 considerations as all HTTP methods as described in [RFC7231]. 279 6. IANA Considerations 281 IANA is requested to update the registration of the SEARCH method in 282 the permanent registry at (see Section 8.1 of [RFC7231]). 285 +-------------+------+------------+---------------+ 286 | Method Name | Safe | Idempotent | Specification | 287 +-------------+------+------------+---------------+ 288 | SEARCH | Yes | Yes | Section 2 | 289 +-------------+------+------------+---------------+ 291 7. Normative References 293 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 294 Requirement Levels", BCP 14, RFC 2119, 295 DOI 10.17487/RFC2119, March 1997, 296 . 298 [RFC4918] Dusseault, L., Ed., "HTTP Extensions for Web Distributed 299 Authoring and Versioning (WebDAV)", RFC 4918, 300 DOI 10.17487/RFC4918, June 2007, 301 . 303 [RFC5323] Reschke, J., Ed., Reddy, S., Davis, J., and A. Babich, 304 "Web Distributed Authoring and Versioning (WebDAV) 305 SEARCH", RFC 5323, DOI 10.17487/RFC5323, November 2008, 306 . 308 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 309 Protocol (HTTP/1.1): Message Syntax and Routing", 310 RFC 7230, DOI 10.17487/RFC7230, June 2014, 311 . 313 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 314 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 315 DOI 10.17487/RFC7231, June 2014, 316 . 318 [RFC7232] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 319 Protocol (HTTP/1.1): Conditional Requests", RFC 7232, 320 DOI 10.17487/RFC7232, June 2014, 321 . 323 [RFC7234] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, 324 Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", 325 RFC 7234, DOI 10.17487/RFC7234, June 2014, 326 . 328 Authors' Addresses 330 Julian Reschke 332 Email: julian.reschke@greenbytes.de 334 Ashok Malhotra 336 Email: ashok.malhotra@oracle.com 338 James M Snell 340 Email: jasnell@gmail.com