Re: NEW PREFERENCE - return=query-result

[James M Snell <[e-mail]>]

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
>>
>>
>>
>>
>