Re: QUERY Verb Proposal

On 1/19/15 2:37 PM, Cody Burleson wrote:
> Hi, Kingsley,
>

Hi Cody,


> Thanks for getting this into a single text-flow form.

No problem.
That's all I did. I haven't stated anything :)

Kingsley

> You state in the intro, the following:
>
> "It is inspired by RFC 5323 
> <http://tools.ietf.org/search/rfc5323> which defines WebDAV Search, 
> although *the details are significantly different.*”
>
> I think I saw in a recent email that it may also be possible for us to 
> just leverage and refine the same proposal. I haven’t had time to look 
> in detail yet, so I am not sure if it is true that what we’d want to 
> propose here is actually “significantly different”. But it does raise 
> the question for me as to whether or not we are should be just 
> building on something “inspired by” RFC 5323, writing an extension to 
> it, which specifically references it with modifications, or if we 
> should be trying to actually modify the scope and further refine RFC 5323.
>
> Thoughts?  I guess at this stage, your text “inspired by” works. We 
> could always do some kind of better merging in the future. But are we 
> sure yet whether or not it’s true there are or will be “significantly 
> different”?
>
>
> From: Kingsley Idehen
> Date: Monday, January 19, 2015 at 12:46 PM
> To: <public-ldp-wg@w3.org <mailto:public-ldp-wg@w3.org>>
> Subject: Re: QUERY Verb Proposal
> Resent-From: <public-ldp-wg@w3.org <mailto:public-ldp-wg@w3.org>>
> Resent-Date: Mon, 19 Jan 2015 18:47:18 +0000
>
> 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