Re: NEW PREFERENCE - return=query-result

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 15:57:04 UTC