Dataspace REST API

URI format
 
<sxh code; gutter: true;>
/ds/<dataspace_name>/collection/{collection_name}? 
  [&{column_name1}[={value1}]…{column_name2}[={value2}]
      [&where=<where clause>]
</sxh>


/ds/<dataspace_name>/dsql&q=<SQL statement>

/ds/<dataspace_name>/fn/{functionName}
[&{param_name1}[={value1}]…{param2_name2}[={value2}]


dataspace_name should be in format <DataspaceType>.<DataspaceName>
==Response Codes==
 
^ Code ^ Description           ^
| 200   | OK  |
| 4xx  | Invalid Request |
| 424  | Unknown Dataspace Resource '.some name..' |
| 425  | Unknown Dataspace Collection Entity '.. some collecton name..' @ Resource '.. ds name..' |
| 426 | Undefined element '.. column name' @  Dataspace Collection ' .. collection name..' |
| 500 | SQL Error |

<sxh code; gutter: true;>


</sxh>

Responses

Dffd – df  

Response format
 
Request format can be set by the following ways
-	requestFormat URL parameter
-	Content-Type header

Response format can be set by the following ways
-	responseFormat and responseMimeType URL parameters
-	Accept header

requestFormat defines how data should be converted before handling. 
responseFormat defines how result data should be converted before writing to output. responseMimeType defines response Content-Type. If responseMimeType not specified Content-Type will depend on responseFormat.
responseFormant/requestFormat parameters overrides header parameters.
Default response format is JSON. 

Mime types	request/response format
application/xml	xml
application/json	json
text/plain	string
application/octet-stream	binary
text/html (for Accept header only)	html
Any mime type, for example application/pdf	Corresponding mime type extension, for example pdf,zip and etc
 
Note: binary response formats applicable for single value results with norowset=true option specified. 
Example:
 - get blob in pdf 
	/ds/TSPACE.MyDS/fn/geDoc?index=1&responseFormat=pdf&norowset=true
 
- get blob in json
	/ds/TSPACE.MyDS/fn/geDoc?index=1&responseFormat=binary&responseMimeType=application/json&norowset=true


DSQL Error Response
 
<sxh XML; gutter: true;>

XML	JSON
<HTTPException>
 <errorPrefix>URL</errorPrefix>
 <errorCode>0</errorCode>
 <detailMessage></detailMessage>
 <state>0</state>
 <severity>SEVERE</severity>
 <stackTrace>0</stackTrace>
</HTTPException>	{
   "HTTPException" : 
   {
      "errorPrefix" : "", 
      "errorCode" : 0, 
      "detailMessage" : ".", 
      "state" : null, 
      "severity" : 
      {
         "Severity" : 
         {
            "value" : "SEVERE"
         }
      }, 
      "stackTrace" : null
   }
}

</sxh>

INSERT/UPDATE/DELETE update count response
 
XML	JSON
<DSResultUpdateCount>
  <updateCount>1</updateCount>
</DSResultUpdateCount >	{
 “DSResultUpdateCount” :
 {
   "updateCount": 1
 }
}
 
Single value response

XML	JSON
<DSResultSingleValue >
  <value>Mile</value>
</DSResultSingleValue >	{
 “DSResultSingleValue” :
 {
   “value”: “Mike”
 }
}

SELECT response
 
Select response is XML/JSON row set representation
For example we have table Customers with the following columns

Column
Id(autoincrement)
firstname
lastname
age
 
select firstname, lastname from Customers

XML	JSON
<DSRowSet>
 <DSRow>
   <firstname></firstname>
   <lastname></lastname>
 <DSRows>
</DSRowSet>	
{
"DSRowSet" : 
[
{ DSRow:
  {
   “firstname”: ““,
   “lastname”:  ““
  }
}
]
}
 
Null response
XML	JSON
<Null/>	{
   "Null" : 
   {
   }
}

NOTE: If suppressJSONType parameter is enabled in API customizer then top element types will be suppressed in json.

JSON serializer customization

To serialize/deserialize request/response object in JSON format internal JSON serializer is used. StreamScape JSON serializer has some parameters that allow to customize serializer. For more detail see JSON serializer documentation and Javadoc. 

JSON serializer customization properties can be customized with requestFormat/responseFormat parameters.

List of configurable JSON properties:

Name	Description	Possible value	Default value
notation	Defines notation type (type or top element).	-	type
-	top_element	 type_element
level	Defines notation level, amount of meta data that define type of serialized objects.	-	none
-	root_element
-	root_enum
-	complex_objects
-	polymorphic_objects
-	polymorphic_maps_and_collecitons
-	polymorphic_primitive_objects
-	primitive_objects
-	enums	-	root_element
-	root_enum
-	polymorphic_objects
-	polymorphic_maps_and_collecitons

prettyprint	Should output JSON be pretty formatted or not.	true or false	false
skipnulls	Should output JSON pretty contain null values or not.	true or false	false

To configure these properties in requestFormat/responseFormat parameters they should be added to format after semicolon and separated by semicolon. List of properties values should be separated by comma.

Examples:

	json;notation=type
	json;level=top_element;level=root_element,complex_objects
	json;notation=type;prettyprint=true;skipnulls=true


Norowset response

`norowset` parameter is applicable for JSON response format only. If ‘norowset=true’ specified in query then JSON response will miss DSRowSet, DSRow, DSResultUpdateCount and DSResultSingleValue wrappers. It will look like following

-	Update count response
     1

-	Single result response
“Mike”

-	Select response
More then one row, more then one column	More then one row, one column
	One row, more then one column	One row, one column


[
{
“column1”:““,
“column2”:““
}
]	[
{
returned object
}
]





	{
“column1”:““,
“column2”:““
}




	{
returned object
}







Norows response

`norows` parameter is applicable for JSON response format only. If ‘norows=false’ specified in query then JSON response will miss DSRow wrapper. It  will look like the following:

Select response
DSRowSet : {
rows:
[
{
“column1”:““,
“column2”:““
}
]
}
Noheader response

`noheader` parameter is applicable for ‘html’ or ‘string’ response formats only. If ‘noheader=true’ specified in the query then result row set formatted in HTML or TEXT will not contain header.
Passing parameters data

Parameters values can be passed by the following ways
-	URL query parameters (for any request and string values)
-	Specifying http{content} or http{content-bytes} for URL query parameters (for PUT and POST request and binary values)
-	As part of multipart/form-data (for PUT and POST request and binary values)
http{content} and http{content-bytes}

If value of parameter in URL query equals to http{content} or http{content-bytes} then this value of this parameter will be read from http request payload. 
Difference between http{content} and http{content-bytes} is following 
-	in case of http{content} binary content will be converted to string in charset specified in request content-type or UTF-8 by default and then serialized according to requestFormat
-	in case http{content-bytes} content will not converted to string or serialized and will be passed to sql request as bytes

Example

POST /ds/mydb/movies?filename=myvideo.mkv&data=http{content-bytes} HTTP/1.1
Content-Type: application/octet-stream
Accept: applicaton/xml
 
… video file data…
multipart/form-data

POST or PUT requests parameters can be passed as parts of multipart/form-data request content. It can be done together or instead of query parameters. 
HTTP request content-type should be set to multipart/form-data. The following part attributes are handled
-	Content-Disposition should be set to form-data
-	name should be set to parameter name
-	content-type if set to application/octet-stream then parameter value will not be converted to string or serialized, otherwise if will be converted to string and serialized according to requestFormat

Examples

POST /ds/mydb/movies?id=1 HTTP/1.1
Content-Type: application/octet-stream
Accept: multipart/form-data
 
------------V2ymHFg03ehbqgZCaKO6jy
Content-Disposition: form-data; name="data"
content-type: application/octet-stream

	… video file data…
 
------------V2ymHFg03ehbqgZCaKO6jy
Content-Disposition: form-data; name="filename"
content-type: plain/text

myvideo.mkv
------------V2ymHFg03ehbqgZCaKO6jy--

Tuple Set

Data to insert/update/function call statements can be passed in tuple set.
Tuple set has the following format

XML	JSON
<TupleSet>
  <columnName1>column value1<columnName1>
…
<columnNameN>column valueN<columnNameN>
</TupleSet>	{
  columnName1 : <columnValue1> 
…
  columnNameN : <columnValueN> 
}

CRUD operations on tables
 
If specified in URL /ds/<dataspace_name>/collection/{collection_name} collection is table then CRUD operations on tables are applicable for this collection.

<sxh dsql; gutter: true;>

HTTP Method	SQL Operation
POST	INSERT
GET	SELECT
PUT	UPDATE
DELETE	DELETE

</sxh>

INSERT operation
 
Method	POST
Path	/ds/<dataspace_name>/collection/<collection_name>
Query Parameters	None
Request Body	Columns and values to insert in multipart/form-data
<column_name1>=<column_value1>&..&<column_nameN>=<column_valueN>

or in TupleSet, in that case useTupleSet=true should be in query
{
   columnName1 : value1,
   ….
   columnNameN : valueN,
}
Response Body	Number of rows inserted.
 
Content-Type should be set to application/x-www-form-urlencoded.

Also parameter can be passed using http{content}/http{content-bytes} or multipart/form-data.

SQL Query
insert into customers columns(firstname, lastname, age) values(“John”, ““, 32);
 
HTTP REST Request
POST /ds/mydb/Customers HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: applicaton/xml
 
Firstname=John&lastname=&age=32
 
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/xml
 
<DSResultUpdateCount>
  <updateCount>1</updateCount>
</DSResultUpdateCount>
 
SELECT operation
 
Method	GET
Path	/ds/<dataspace_name>/ collection/<collection_name>?
[<column_name1>&…<column_nameN>]&<where clause>
Query Parameters	‘*’ can be used instead of column name and means all columns.
Where clause, can be defined in two ways:
•	where(<DSQL where clause>)
•	where=<DSQL where clause>
Limit and order by statements
•	limit=<N>
•	order_by=<column_name>
Request Body	None
Response Body	Select result as XML or JSON, depends on Accept type.
 
NOTE: All special symbols like (‘ > < <= =) in parameter values and where clauses should be escaped.
 
SQL Query
select firstname, lastname from customers where age<30
 
HTTP REST Request
GET /ds/myds/Customers/?firstname&lastname&where=age%3D<30 HTTP/1.1
Accept: applicaton/xml
 
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/xml
 
<DSRowSet>
 <DSRow>
  <firstname>Mike</firstname>
  <lastname></lastname>
 </DSRow>
 <DSRow>
  <firstname>Peter</firstname>
  <lastname></lastname>
 </DSRow>
</DSRowSet>
 
SQL Query
select firstname, lastname from customers where age>30
 
HTTP REST Request
GET /ds/mydb/Customers/?firstname&lastname&where(age>30) HTTP/1.1
Accept: applicaton/json
 
HTTP Response
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/json
 
{ 
 "DSRowSet" :
  {
      "rows" : 
      [
         {
            "firstname" : "Bill", 
            "lastname" : ““, 
         }
      ]
   }
}
 
UPDATE operation
 
Method	PUT
Path	/ds/<dataspace_name>/ collection/<collection_name>?<columns and values to update><where clause>
Query Parameters	Columns and values to update:
<column_name1>=<column_value1>&..&<column_nameN>=<column_valueN>

Where clause is optional, can be defined in two ways:
•	where(<DSQL where clause>)
•	where=<DSQL where clause>
Request Body	If no parameters specified in query, TupleSet can be specified, in that case useTupleSet=true should be in query
Response Body	Number of rows updated.
 
Also parameter can be passed using http{content}/http{content-bytes} or multipart/form-data.

SQL Query
update customers set age=31 where firstname=John and id>3;
 
HTTP REST Request
PUT /ds/mydb/Customers?age=32where=firstname%3dJohn&id%3d>3 HTTP/1.1
Accept: applicaton/json
  
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/json
 
{
 “DSResultUpdateCount”:
 {
  “updateCount” : 1
 }
}
 
DELETE operation
 
Method	DELETE
Path	/ds/<dataspace_name>/ collection/<collection_name>?<where clause>
Query Parameters	Optional.
Where clause, can be defined in two ways:
•	where(<DSQL where clause>)
•	where=<DSQL where clause>
Request Body	None
Response Body	Number of rows deleted.
 
SQL Query
delete from customers where age=32;    
 
HTTP REST Request
DELETE /repository/mydb/Customers?age=32 HTTP/1.1
Accept: applicaton/json
 
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/json
 
{
 “DSResultUpdateCount”:
 {
  “updateCount” : 1
 }
}
Operations on queues

If specified in URL /ds/<dataspace_name>[/{collection_name} collection is queue then CRUD operations on queues are applicable for this collection.

HTTP Method	SQL Operation
PUT/POST	PUT
GET	READ
DELETE	TAKE

PUT operation
Adds element to the top of the queue.

Method	PUT/POST
Path	/ds/<dataspace_name>/<collection_name>
Query Parameters	If request is PUT 
data=<serialized object to add>
requestFormat query parameter/Content-Type header defines data format
Request Body	If request is POST the above query parameters.
Response Body	DSResult with update count

Also parameter can be passed using http{content}/http{content-bytes} or multipart/form-data.

HTTP REST Request
PUT /ds/mydb/Customers?data=<Customer>…</Customer> HTTP/1.1
Content-Type: applicaton/xml
Accept: applicaton/xml
 
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/xml
 
<DSResponseUpdateCount>
  <updateCount>1</updateCount>
</DSResponseUpdateCount>

READ operaton
Reads element from the top of the queue. If there are no elements in the queue Null object is returned.

Method	GET
Path	/ds/<dataspace_name>/<collection_name[?selector=<selector>]
Query Parameters	If queue is event queue selector can be specified
?selector=<selector>
Request Body	None
Response Body	Serialized read object if success.

HTTP REST Request
GET /ds/mydb/Customers HTTP/1.1
Accept: applicaton/xml
 
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/xml
 
<Customer>
  <firstname>1</firstname>
…
</Customer>
TAKE operation
Reads and remove element from the top of the queue. If there are no elements in the queue Null object is returned.

Method	DELETE
Path	/ds/<dataspace_name>/<collection_name[?selector=<selector>]
Query Parameters	If queue is event queue selector can be specified
?selector=<selector>
Request Body	None
Response Body	Serialized read object if success.

HTTP REST Request
GET /ds/mydb/Customers HTTP/1.1
Accept: applicaton/xml
 
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/xml
 
<Customer>
  <firstname>1</firstname>
…
</Customer>

Function call
Method	POST/GET
Path	/ds/<dataspace_name>/fn/<function name>?
Query Parameters	<param_name1>=<param_value1>&…
Request Body	If no parameters specified in query, TupleSet can be specified, in that case useTupleSet=true should be in query
Response Body	DSResult or DSRowSet

Also parameter can be passed using http{content}/http{content-bytes} or multipart/form-data.

SQL Query
call getName(age age); 
 
HTTP REST Request
GET /ds/mydb/fn/getName?age=30 HTTP/1.1
Accept: applicaton/xml
 
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/xml
 
<DSResultSingleValue>
  <value>Bill</value>
</DSResultSingleValue>
Any DSQL statement
 
Method	POST/GET
Path	/ds/dsql/<dataspace_name>
Query Parameters	SQL query if request is GET
Request Body	SQL query If request is POST
q=<any sql query>
Response Body	DSResult or DSRowSet.
 
SQL Query
Select name from customers where age>30 limit 2; 
 
HTTP REST Request
POST /ds/mydb HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: applicaton/xml
 
q=select name from customers where age>30 limit 2
 
HTTP Response
HTTP/1.1 200 OK
Content-Type: applicaton/xml
 
<DSRowSet>
 <DSRow>
  <name>Bill</name>
</DSRow>
<DSRow>
  <name>Steeve</name>
</DSRow>
</DSRowSet>
