draft-snell-search-method-02.txt		draft-snell-search-method-latest.txt
	Network Working Group J. Reschke		Network Working Group J. Reschke
	Internet-Draft greenbytes		Internet-Draft greenbytes
	Updates: 5323 (if approved) A. Malhotra		Updates: 5323 (if approved) A. Malhotra
	Intended status: Standards Track		Intended status: Standards Track
	Expires: March 6, 2021 J.M. Snell		Expires: October 12, 2024 J.M. Snell
	September 2, 2020		April 10, 2024
	HTTP SEARCH Method		HTTP SEARCH Method
	draft-snell-search-method-02		draft-snell-search-method-latest
	Abstract		Abstract
	This specification updates the definition and semantics of the HTTP		This specification updates the definition and semantics of the HTTP
	SEARCH request method originally defined by RFC 5323.		SEARCH request method originally defined by RFC 5323.
	Editorial Note		Editorial Note
	This note is to be removed before publishing as an RFC.		This note is to be removed before publishing as an RFC.
	skipping to change at page 1, line 48 ¶		skipping to change at page 1, line 48 ¶
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF). Note that other groups may also distribute		Task Force (IETF). Note that other groups may also distribute
	working documents as Internet-Drafts. The list of current Internet-		working documents as Internet-Drafts. The list of current Internet-
	Drafts is at https://datatracker.ietf.org/drafts/current/.		Drafts is at https://datatracker.ietf.org/drafts/current/.
	Internet-Drafts are draft documents valid for a maximum of six months		Internet-Drafts are draft documents valid for a maximum of six months
	and may be updated, replaced, or obsoleted by other documents at any		and may be updated, replaced, or obsoleted by other documents at any
	time. It is inappropriate to use Internet-Drafts as reference		time. It is inappropriate to use Internet-Drafts as reference
	material or to cite them other than as "work in progress."		material or to cite them other than as "work in progress."
	This Internet-Draft will expire on March 6, 2021.		This Internet-Draft will expire on October 12, 2024.
	Copyright Notice		Copyright Notice
	Copyright (c) 2020 IETF Trust and the persons identified as the		Copyright (c) 2024 IETF Trust and the persons identified as the
	document authors. All rights reserved.		document authors. All rights reserved.
	This document is subject to BCP 78 and the IETF Trust's Legal		This document is subject to BCP 78 and the IETF Trust's Legal
	Provisions Relating to IETF Documents (https://trustee.ietf.org/		Provisions Relating to IETF Documents (https://trustee.ietf.org/
	license-info) in effect on the date of publication of this document.		license-info) in effect on the date of publication of this document.
	Please review these documents carefully, as they describe your rights		Please review these documents carefully, as they describe your rights
	and restrictions with respect to this document. Code Components		and restrictions with respect to this document. Code Components
	extracted from this document must include Revised BSD License text as		extracted from this document must include Revised BSD License text as
	described in Section 4.e of the Trust Legal Provisions and are		described in Section 4.e of the Trust Legal Provisions and are
	provided without warranty as described in the Revised BSD License.		provided without warranty as described in the Revised BSD License.
	Table of Contents		Table of Contents
	1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2		1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
	2. SEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . 4		2. SEARCH . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
	3. The "Accept-Search" Header Field . . . . . . . . . . . . . . 5		3. The "Accept-Search" Header Field . . . . . . . . . . . . . . 5
	4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5		4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 6
	4.1. Simple SEARCH with a Direct Response . . . . . . . . . . 6		4.1. Simple SEARCH with a Direct Response . . . . . . . . . . 6
	4.2. Simple SEARCH with indirect response (303 See Other) . . 6		4.2. Simple SEARCH with indirect response (303 See Other) . . 6
	5. Security Considerations . . . . . . . . . . . . . . . . . . . 7		5. Security Considerations . . . . . . . . . . . . . . . . . . . 7
	6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7		6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7
	7. Normative References . . . . . . . . . . . . . . . . . . . . 7		7. Normative References . . . . . . . . . . . . . . . . . . . . 7
	Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8		Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8
	1. Introduction		1. Introduction
	This specification updates the HTTP SEARCH method originally defined		This specification updates the HTTP SEARCH method originally defined
	skipping to change at page 3, line 44 ¶		skipping to change at page 3, line 44 ¶
	set allowed by URL standards. Such encoding can add significant		set allowed by URL standards. Such encoding can add significant
	complexity, introduce bugs, or otherwise reduce the overall		complexity, introduce bugs, or otherwise reduce the overall
	visibility of the query being requested.		visibility of the query being requested.
	As an alternative to using GET, many implementations make use of the		As an alternative to using GET, many implementations make use of the
	HTTP POST method to perform queries, as illustrated in the example		HTTP POST method to perform queries, as illustrated in the example
	below. In this case, the input parameters to the search operation		below. In this case, the input parameters to the search operation
	are passed along within the request payload as opposed to using the		are passed along within the request payload as opposed to using the
	request URI.		request URI.
	A typical use of HTTP GET for requesting a search		A typical use of HTTP POST for requesting a search
	POST /feed HTTP/1.1		POST /feed HTTP/1.1
	Host: example.org		Host: example.org
	Content-Type: application/x-www-form-urlencoded		Content-Type: application/x-www-form-urlencoded
	q=foo&limit=10&sort=-published		q=foo&limit=10&sort=-published
	This variation, however, suffers from the same basic limitation as		This variation, however, suffers from the same basic limitation as
	GET in that it is not readily apparent -- absent specific knowledge		GET in that it is not readily apparent -- absent specific knowledge
	of the resource and server to which the request is being sent -- that		of the resource and server to which the request is being sent -- that
	a search operation is what is being requested. Web applications use		a search operation is what is being requested. Web applications use
	skipping to change at page 4, line 41 ¶		skipping to change at page 4, line 41 ¶
	The payload returned in response to a SEARCH cannot be assumed to be		The payload returned in response to a SEARCH cannot be assumed to be
	a representation of the resource identified by the effective request		a representation of the resource identified by the effective request
	URI.		URI.
	The body payload of the request defines the query. Implementations		The body payload of the request defines the query. Implementations
	MAY use a request body of any content type with the SEARCH method;		MAY use a request body of any content type with the SEARCH method;
	however, for backwards compatibility with existing WebDAV		however, for backwards compatibility with existing WebDAV
	implementations, SEARCH requests that use the text/xml or		implementations, SEARCH requests that use the text/xml or
	application/xml content types MUST be processed per the requirements		application/xml content types MUST be processed per the requirements
	established by [RFC5323].		established by [RFC5323].
			// This can be relaxed to XML with a document element in the "DAV:"
			// namespace, or even to the two element names mentionbed in
			// Section 2.2.2 of [RFC5323].
	SEARCH requests are both safe and idempotent with regards to the		SEARCH requests are both safe and idempotent with regards to the
	resource identified by the request URI. That is, SEARCH requests do		resource identified by the request URI. That is, SEARCH requests do
	not alter the state of the targeted resource. However, while		not alter the state of the targeted resource. However, while
	processing a search request, a server can be expected to allocate		processing a search request, a server can be expected to allocate
	computing and memory resources or even create additional HTTP		computing and memory resources or even create additional HTTP
	resources through which the response can be retrieved.		resources through which the response can be retrieved.
	A successful response to a SEARCH request is expected to provide some		A successful response to a SEARCH request is expected to provide some
	indication as to the final disposition of the search operation. For		indication as to the final disposition of the search operation. For
	skipping to change at page 5, line 17 ¶		skipping to change at page 5, line 21 ¶
	indirectly to the SEARCH request by returning a 3xx Redirection with		indirectly to the SEARCH request by returning a 3xx Redirection with
	a Location header specifying an alternate Request URI from which the		a Location header specifying an alternate Request URI from which the
	search results can be retrieved using an HTTP GET request. Various		search results can be retrieved using an HTTP GET request. Various
	non-normative examples of successful SEARCH responses are illustrated		non-normative examples of successful SEARCH responses are illustrated
	in Section 4.		in Section 4.
	The response to a SEARCH request is not cacheable. It ought to be		The response to a SEARCH request is not cacheable. It ought to be
	noted, however, that because SEARCH requests are safe and idempotent,		noted, however, that because SEARCH requests are safe and idempotent,
	responses to a SEARCH MUST NOT invalidate previously cached responses		responses to a SEARCH MUST NOT invalidate previously cached responses
	to other requests directed at the same effective request URI.		to other requests directed at the same effective request URI.
			// By default, that is. We need to figure out under which conditions
			// we can make the result cacheable.
	The semantics of the SEARCH method change to a "conditional SEARCH"		The semantics of the SEARCH method change to a "conditional SEARCH"
	if the request message includes an If-Modified-Since, If-Unmodified-		if the request message includes an If-Modified-Since, If-Unmodified-
	Since, If-Match, If-None-Match, or If-Range header field ([RFC7232]).		Since, If-Match, If-None-Match, or If-Range header field ([RFC7232]).
	A conditional SEARCH requests that the query be performed only under		A conditional SEARCH requests that the query be performed only under
	the circumstances described by the conditional header field(s). It		the circumstances described by the conditional header field(s). It
	is important to note, however, that such conditions are evaluated		is important to note, however, that such conditions are evaluated
	against the state of the target resource itself as opposed to the		against the state of the target resource itself as opposed to the
	collected results of the search operation.		collected results of the search operation.
	skipping to change at page 6, line 9 ¶		skipping to change at page 6, line 17 ¶
	The non-normative examples in this section make use of a simple,		The non-normative examples in this section make use of a simple,
	hypothetical plain-text based query syntax based on SQL with results		hypothetical plain-text based query syntax based on SQL with results
	returned as comma-separated values. This is done for illustration		returned as comma-separated values. This is done for illustration
	purposes only. Implementations are free to use any format they wish		purposes only. Implementations are free to use any format they wish
	on both the request and response.		on both the request and response.
	4.1. Simple SEARCH with a Direct Response		4.1. Simple SEARCH with a Direct Response
	A simple query with a direct response:		A simple query with a direct response:
	SEARCH /contacts HTTP/1.1		SEARCH /contacts HTTP/1.1
	Host: example.org		Host: example.org
	Content-Type: text/query		Content-Type: text/query
	Accept: text/csv		Accept: text/csv
	select surname, givenname, email limit 10		select surname, givenname, email limit 10
	Response:		Response:
	HTTP/1.1 200 OK		HTTP/1.1 200 OK
	Content-Type: text/csv		Content-Type: text/csv
	surname, givenname, email		surname, givenname, email
	Smith, John, john.smith@example.org		Smith, John, john.smith@example.org
	Jones, Sally, sally.jones@example.com		Jones, Sally, sally.jones@example.com
	Dubois, Camille, camille.dubois@example.net		Dubois, Camille, camille.dubois@example.net
	4.2. Simple SEARCH with indirect response (303 See Other)		4.2. Simple SEARCH with indirect response (303 See Other)
	A simple query with an Indirect Response (303 See Other)		A simple query with an Indirect Response (303 See Other):
	SEARCH /contacts HTTP/1.1		SEARCH /contacts HTTP/1.1
	Host: example.org		Host: example.org
	Content-Type: text/query		Content-Type: text/query
	Accept: text/csv		Accept: text/csv
	select surname, givenname, email limit 10		select surname, givenname, email limit 10
	Response:		Response:
	HTTP/1.1 303 See Other		HTTP/1.1 303 See Other
	Location: http://example.org/contacts/query123		Location: http://example.org/contacts/query123
	Fetch Query Response:		Fetch Query Response:
	GET /contacts/query123 HTTP/1.1		GET /contacts/query123 HTTP/1.1
	Host: example.org		Host: example.org
	Response:		Response:
	HTTP/1.1 200 OK		HTTP/1.1 200 OK
	Content-Type: text/csv		Content-Type: text/csv
	surname, givenname, email		surname, givenname, email
	Smith, John, john.smith@example.org		Smith, John, john.smith@example.org
	Jones, Sally, sally.jones@example.com		Jones, Sally, sally.jones@example.com
	Dubois, Camille, camille.dubois@example.net		Dubois, Camille, camille.dubois@example.net
	5. Security Considerations		5. Security Considerations
	The SEARCH method is subject to the same general security		The SEARCH method is subject to the same general security
	considerations as all HTTP methods as described in [RFC7231].		considerations as all HTTP methods as described in [RFC7231].
	6. IANA Considerations		6. IANA Considerations
	IANA is requested to update the registration of the SEARCH method in		IANA is requested to update the registration of the SEARCH method in
	the permanent registry at <http://www.iana.org/assignments/http-		the permanent registry at <http://www.iana.org/assignments/http-
End of changes. 19 change blocks.
	34 lines changed or deleted		39 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/