Re: QUERY Verb Proposal

On 1/19/15 11:08 AM, Ashok Malhotra wrote:
> I'm attaching a ppt and a brief writeup.
> I'm happy to create a more formal writeup
> along the lines of the WebDAV SEARCH proposal
> of the PATCH Verb Proposal.
>
> Anyone want to get involved and help?

Ashok,

Here's the proposal, unshackled from the current PowerPoint and Word Docs:

Proposal for a New HTTP Verb: QUERY


  1Introduction

This is a proposal for a new HTTP verb: QUERY.It is inspired by RFC 5323 
<http://tools.ietf.org/search/rfc5323> which defines WebDAV Search, 
although the details are significantly different.The search or query (we 
use the words interchangeably in this document) specification is in the 
body of the QUERY request.The query searches the Resource URL on which 
the request is made.If the query succeeds, the results are contained in 
the body of response.

QUERY (return selected parts of the resource) is related to GET as PATCH 
– RFC 5789-- (update selected parts of the resource) is to PUT In some 
sense it can be looked at as a GET with a body, where the body contains 
the selection information.


  2Running a Query

The client makes a HTTP QUERY request to initiate a server-side search. 
The body of the request contains the query specification.The query may 
be specified using several different grammars.The media-type of the 
specification MUST be indicated in the content-type header of the request.

If the response is requested in a specific format, Accept headers can be 
used to indicate the type of response.

If the query succeeds, a 200 OK response is returned.Other HTTP response 
codes can be returned in other circumstances.For example a 400 would be 
returned if the query was syntactically incorrect.

QUERY is a safe method.It does not modify the resource and has no 
effects other executing the query and returning the results.See RFC 2616 
Section 9.1.1 <http://tools.ietf.org/search/rfc2616#section-9.1.1>. It 
is also idempotent. See RFC 2616 Section 9.1.2. 
<http://tools.ietf.org/search/rfc2616#section-9.1.2>

The results of a QUERY request can be cached. Thus, if the same query is 
executed on the same resource the results can be served from the cache 
as long as the underlying resource has not changed.Cache control headers 
and ETag headers can be used with the QUERY request as appropriate


  3Persisting Queries

Queries can be stored on the server using a PUT, modified using a POST 
or PATCH and deleted using a DELETE.


  4Running a Stored Query

To execute a stored query, the URL of the stored query can be contained 
in the body of the request or in a link header with rel = 
“query”.Alternately, you do a GET on the URL of the query concatenated 
with “/results”.This will return the query result either by 
re-evaluating the query or by serving it from the cache.

Stored queries can be parameterized.If the query is a parameterized 
query, then appropriate query parameters must be supplied in the request 
URL query string. For example, if the query requires two parameters, the 
query string in the request may be of the form “?var1=value1&var2=value2”.

If fewer values are supplied in the query string than there are 
parameters in the query, a 400 Malformed Request would be 
returned.Excess values in query string would be ignored. If the 
parameter names in the query string do not match the names in the query, 
400 would be returned.Similarly, if the datatypes of the values in the 
query string do not match the datatypes expected for the query variables 
a 400 would be returned.


  5Discovering Capabilities

Clients can determine whether a server supports theQUERY  method by making an OPTIONS request on the server URL or a dataURL.This is a normal invocation of OPTIONS as defined inSection 9.2 of [RFC2616]  <http://tools.ietf.org/search/rfc2616#section-9.2>.  IfQUERY  is supported, the serverMUST listQUERY  in the Allow header defined inSection 14.7 of [RFC2616]  <http://tools.ietf.org/search/rfc2616#section-14.7>.   Servers supportingQUERY  must  also include theQUERY  header in the OPTIONS response. This header identifies metadata for the search grammars supported by the resource.   The value is a non-empty list of URLs that indicate the metadata for the supported grammars.        


  6Header Fields


    6.1Request Header Fields


      6.1.1Content-Type

Indicates the media-type of the search specification


      6.1.2Accept

Indicates the format of the response


      6.1.3cacheable flag (optional, default=false)

To indicate whether or not to cache results between multiple query 
executions. If enabled, query results will return an ETag that client 
can use between query execution requests.


      6.1.4queryURL

Indicates the location of a stored query..

Other HTTP request headers have their usual meanings.


    6.2Response Header Fields


      6.2.1Allow

If the server supports the SEARCH verb then SEARCH must be included in 
the Allow header in response to a OPTIONS request


      6.2.2Search

If the server supports the SEARCH verb then response to an OPTIONS 
request must include a non-empty Search header listing the URLs of the 
metadata for the query syntaxes supported.

Other HTTP response headers have their usual meanings.



-- 
Regards,

Kingsley Idehen 
Founder & CEO
OpenLink Software
Company Web: http://www.openlinksw.com
Personal Weblog 1: http://kidehen.blogspot.com
Personal Weblog 2: http://www.openlinksw.com/blog/~kidehen
Twitter Profile: https://twitter.com/kidehen
Google+ Profile: https://plus.google.com/+KingsleyIdehen/about
LinkedIn Profile: http://www.linkedin.com/in/kidehen
Personal WebID: http://kingsley.idehen.net/dataspace/person/kidehen#this