Re: NEW PREFERENCE - return=query-result

[Phil Hunt <[e-mail]>]

If you mean have multiple endpoints I agree. 

Another possibility that has been suggested to me is using content-type to signal processing behavior. But this might be a good example as to why it is not the best. It strikes me as more confusing when the content is the same but using content type to signal processing instructions. It then gets complex if you want to signal different permutations and combinations of processing behaviors. 

"post creates a resource" becomes nice and consistent if we move reporting processing functions out of POST(things that do not change state) into a new method like SEARCH. 

Phil

> On Sep 11, 2015, at 14:37, Matthew Kerwin <[e-mail]> wrote:
> 
> If a resource can be coded to have two behaviours (and branch on the 'prefer' header), why not just code two resources?
> 
> It seems much cleaner to me to have one URI that always stores a query and returns 201, and another that always executes immediately and returns 200, when POSTed to.
> 
> They're both valid uses of POST.
> 
>> On 12/09/2015 6:08 AM, "Phil Hunt" <[e-mail]> wrote:
>> 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
>> >