Re: QUERY Verb Proposal

On 1/19/15 1:59 PM, ashok malhotra wrote:
> 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.

Ideally, this should be a mechanism for SPARQL and other query language 
payloads.

Kingsley
>
> 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
>


-- 
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