Re: QUERY Verb Proposal

Thank you Kingsley!

We need to add a bit of motivation along the following lines:
We need a mechanism to query and return parts of complex resources
such as RDF graphs, LDP collections etc.  Query parameters are inadequate
to express the complexity of the queries required.  Also, the query may
often exceed the maximum length of the Request-URI allowed in HTTP
requests.

All the best, Ashok

On 1/19/2015 1:46 PM, Kingsley Idehen wrote:
> 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