Re: NEW PREFERENCE - return=query-result

[Phil Hunt <[e-mail]>]

Agree. If we had search then I would say post should create a resource by default. 

But without search I think many are stuck with using post to search given concerns about passing PII and other restricted info on url with GET. 

Phil

> On Sep 11, 2015, at 10:10, James M Snell <[e-mail]> 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
>