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