Re: QUERY Verb Proposal

Building upon Kingsley’s step, I’ve put the initial text in the wiki; we can iterate there:

https://www.w3.org/2012/ldp/wiki/Proposal_for_HTTP_QUERY_Verb




From: Cody Burleson
Date: Monday, January 19, 2015 at 1:37 PM
To: Kingsley Idehen, "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: Monday, January 19, 2015 at 1:37 PM

Hi, Kingsley,

Thanks for getting this into a single text-flow form. 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

1     Introduction
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.
2     Running 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
3     Persisting Queries
Queries can be stored on the server using a PUT, modified using a POST or PATCH and deleted using a DELETE.
4     Running 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.

5     Discovering Capabilities

Clients can determine whether a server supports the QUERY method by making an OPTIONS request on the server URL or a dataURL. This is a normal invocation of OPTIONS as defined in Section 9.2 of [RFC2616]<http://tools.ietf.org/search/rfc2616#section-9.2>. If QUERY is supported, the server MUST list QUERY in the Allow header defined in Section 14.7 of [RFC2616]<http://tools.ietf.org/search/rfc2616#section-14.7>.  Servers supporting QUERY must also include the QUERY 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.

6     Header Fields
6.1           Request Header Fields
6.1.1        Content-Type
Indicates the media-type of the search specification
6.1.2        Accept
Indicates the format of the response
6.1.3        cacheable 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.4        queryURL
Indicates the location of a stored query.  .
Other HTTP request headers have their usual meanings.
6.2           Response Header Fields
6.2.1        Allow
If the server supports the SEARCH verb then SEARCH must be included in the Allow header in response to a OPTIONS request
6.2.2        Search
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