Re: NEW PREFERENCE - return=query-result

[Ning Dong <[e-mail]>]

Yes, that is right. We'll need two requests though: one to create the query definition resource, and one to get the result.

Thanks.

Ning

On 9/11/2015 10:10 AM, James M Snell wrote:
> To be honest, I'm entirely  -1 on a preference for query-result. If
> you want something like this, use PUT or POST to create the stored
> query, then create a new resource that you can either use GET or
> SEARCH (http://tools.ietf.org/html/draft-snell-search-method-00) on.
> In my opinion, `query-result` would entirely be an abuse of the
> preference mechanism.
> 
> On Fri, Sep 11, 2015 at 8:56 AM, Phil Hunt <[e-mail]> wrote:
>> This is difficult. Two conventions are in collision.  The definition of post to create a resource and the expectation that a query returns a result.
>> 
>> I would maybe tip the scales in favor of what most Oracle apis would need as a default.
>> 
>> Would it be true that clients want to create stored searches by default?
>> 
>> Phil
>> 
>>> On Sep 10, 2015, at 14:49, Ning Dong <[e-mail]> wrote:
>>> 
>>> Hi,
>>>    Could you please review the request of adding a new value for return prefer header?
>>> 
>>>    The new value is "query-result", which is used when creating a query definition resource with POST or PUT request.
>>>    The client would like the server to create the query definition resource, but also execute the query and return the query result.
>>>    For example,
>>>    POST /employees/searches HTTP/1.1
>>>    Host: example.org
>>>    Content-Type: application/json
>>>    Prefer: return=query-result
>>> 
>>>    {
>>>        "q": "name eq foo",
>>>        "fields": ["name","age","startdate"],
>>>        "orderBy": ["name","age:desc"]
>>>    }
>>> 
>>>    This above resource defines a query (equivalent to select name, age, startdate from employees where employees.name='foo' order by name, age desc).
>>>    Without the Prefer: return=query-result header, the server would just create a new resource and return a 201 response.
>>>    If server honors the prefer header, then the server will not only create a new resource, but also execute the query based on the query definition.
>>>    The response body will contain the result of the query execution, such as:
>>>    201 Created
>>>    Preference-Applied: return=query-result
>>>    Location: http://example.com/employees/searches/q1
>>>    Content-Location: http://example.com/employees/searches/q1/result
>>> 
>>>    {
>>>      "items": [
>>>        {"name": "foo",
>>>         "age": 35,
>>>         "startdate": "2008-02-15"}
>>>      ]
>>>    }
>>> 
>>> o  Preference: return
>>> 
>>>  o  Value: query-result
>>> 
>>>  o  Optional Parameters: n/a
>>> 
>>>  o  Description: It is used to indicate that result of the query execution is preferred in the response.
>>> 
>>>  o  Reference: Oracle will add a new sub type (type=query-def) in application/vnd.oracle.resource+json media type. This new sub type uses return=query-result prefer header.
>>>     The application/vnd.oracle.resource+json media type is defined at:
>>>     http://www.oracle.com/webfolder/technetwork/tutorials/appdevinfo/New%20REST%20Media%20Type.pdf
>>> 
>>>  o  Notes: It is related to another request to add "transient" prefer header.
>>> 
>>> 
>>>    Thanks and appreciate your review.
>>> 
>>> 
>>> Ning
>>> 
>>> 
>>> 
>>>