NEW PREFERENCE - return=query-result

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 11:39:46 UTC