Re: [Moderator Action] NEW PREFERENCE - return=query-result

Phil,
   I think it is hard to say. I think most cases client probably doesn't want to create a stored search. They just want to execute the query.

   What do you suggest to make the proposal more general and useful for other use cases? We have a very specific use case and very specific way of solving the issue. It might not fly for other people, I guess.

   Thanks.

Ning

On 9/11/2015 8:56 AM, Phil Hunt 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 <ning.dong@oracle.com> 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
>> 
>> 
>> 
>>

Received on Friday, 11 September 2015 16:57:12 UTC