idnits 2.17.1 draft-snell-search-method-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: ---------------------------------------------------------------------------- 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 (April 10, 2015) is 3304 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 294, but no explicit reference was found in the text == Unused Reference: 'RFC7234' is defined on line 311, 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: October 12, 2015 6 J. Snell 7 April 10, 2015 9 HTTP SEARCH Method 10 draft-snell-search-method-00 12 Abstract 14 This specification updates the definition and semantics of the HTTP 15 SEARCH request method previously 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 http://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 October 12, 2015. 34 Copyright Notice 36 Copyright (c) 2015 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 (http://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 . . . . . . . . . . . . . . . . . . . . . . . 7 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 by a client 153 to ask the server to perform a query operation (described by the 154 request payload) over some set of data scoped to the effective 155 request URI. The payload returned in response to a SEARCH cannot be 156 assumed to be a representation of the resource identified by the 157 effective request URI. 159 The body of the request defines the query. Implementations MAY use a 160 request body of any content type with the SEARCH method; however, for 161 backwards compatibility with existing WebDAV implementations, SEARCH 162 requests that use the text/xml or application/xml content types MUST 163 be processed in exact accordance with the requirements established by 164 [RFC5323]. 166 SEARCH requests are both safe and idempotent with regards to the 167 resource identified by the request URI. That is, the performance of 168 a search is not expected to alter the state of the targeted resource. 169 However, while processing a search request, a server can be expected 170 to allocate computing and memory resources or even create additional 171 HTTP resources through which the response to the search can be 172 retrieved. 174 A successful response to a SEARCH request is expected to provide some 175 indication as to the final disposition of the search operation. For 176 instance, a successful search that yields no results can be 177 represented by a 204 No Content response. If the response includes a 178 body payload, the payload is expected to describe the results of the 179 search operation. In some cases, the search arbiter might choose to 180 respond indirectly to the SEARCH request by returning a 3xx 181 Redirection with a Location header specifying an alternate Request 182 URI from which the search results can be retrieved by using an HTTP 183 GET request. Various non-normative examples of successful SEARCH 184 responses are illustrated in Section 4. 186 The response to a SEARCH request is not cacheable. It ought to be 187 noted, however, that because SEARCH requests are safe and idempotent, 188 responses to a SEARCH MUST NOT invalidate previously cached responses 189 to other requests directed at the same effective request URI. 191 The semantics of the SEARCH method change to a "conditional SEARCH" 192 if the request message includes an If-Modified-Since, If-Unmodified- 193 Since, If-Match, If-None-Match, or If-Range header field ([RFC7232]). 194 A conditional SEARCH requests that the query be performed only under 195 the circumstances described by the conditional header field(s). It 196 is important to note, however, that such conditions are evaluated 197 against the state of the target resource itself as opposed to the 198 collected results of the search operation. 200 3. The "Accept-Search" Header Field 202 The "Accept-Search" response header field MAY be used by servers to 203 directly signal support for the SEARCH method while identifying the 204 specific query format Content-Type's that can be used. 206 Accept-Search = "Accept-Search" ":" 1#media-type 208 The Accept-Search header specifies a comma-separated listing of media 209 types (with optional parameters) as defined by [RFC7231], 210 Section 3.1.1.1. 212 4. Examples 214 The non-normative examples in this section make use of a simple, 215 hypothetical plain-text based query syntax based on SQL with results 216 returned as comma-separated values. This is done for illustration 217 purposes only. Implementations are free to use any format they wish 218 on both the request and response. 220 4.1. Simple SEARCH with a Direct Response 222 A simple SPAQRL query with a Direct Response: 224 SEARCH /contacts HTTP/1.1 225 Host: example.org 226 Content-Type: text/query 227 Accept: text/csv 229 select surname, givenname, email limit 10 231 Response: 233 HTTP/1.1 200 OK 234 Content-Type: text/csv 236 surname, givenname, email 237 Smith, John, john.smith@example.org 238 Jones, Sally, sally.jones@example.com 239 Dubois, Camille, camille.dubois@example.net 241 4.2. Simple SEARCH with Indirect Response (303 See Other) 243 A simple SPAQRL query with an Indirect Response (303 See Other) 245 SEARCH /contacts HTTP/1.1 246 Host: example.org 247 Content-Type: text/query 248 Accept: text/csv 250 select surname, givenname, email limit 10 252 Response: 254 HTTP/1.1 303 See Other 255 Location: http://example.org/contacts/query123 257 Fetch Query Response: 259 GET /contacts/query123 HTTP/1.1 260 Host: example.org 262 Response: 264 HTTP/1.1 200 OK 265 Content-Type: text/csv 267 surname, givenname, email 268 Smith, John, john.smith@example.org 269 Jones, Sally, sally.jones@example.com 270 Dubois, Camille, camille.dubois@example.net 272 5. Security Considerations 274 The SEARCH method is subject to the same general security 275 considerations as all HTTP methods as described in [RFC7231]. 277 6. IANA Considerations 279 IANA is requested to update the registration of the SEARCH method in 280 the permanent registry at (see Section 8.1 of [RFC7231]). 283 +-------------+------+------------+---------------+ 284 | Method Name | Safe | Idempotent | Specification | 285 +-------------+------+------------+---------------+ 286 | SEARCH | Yes | Yes | Section 2 | 287 +-------------+------+------------+---------------+ 289 7. Normative References 291 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 292 Requirement Levels", BCP 14, RFC 2119, March 1997. 294 [RFC4918] Dusseault, L., "HTTP Extensions for Web Distributed 295 Authoring and Versioning (WebDAV)", RFC 4918, June 2007. 297 [RFC5323] Reschke, J., Reddy, S., Davis, J., and A. Babich, "Web 298 Distributed Authoring and Versioning (WebDAV) SEARCH", RFC 299 5323, November 2008. 301 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 302 (HTTP/1.1): Message Syntax and Routing", RFC 7230, June 303 2014. 305 [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 306 (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. 308 [RFC7232] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 309 (HTTP/1.1): Conditional Requests", RFC 7232, June 2014. 311 [RFC7234] Fielding, R., Nottingham, M., and J. Reschke, "Hypertext 312 Transfer Protocol (HTTP/1.1): Caching", RFC 7234, June 313 2014. 315 Authors' Addresses 317 Julian Reschke 319 Email: julian.reschke@greenbytes.de 321 Ashok Malhotra 323 Email: ashok.malhotra@oracle.com 324 James M Snell 326 Email: jasnell@gmail.com