API Overview

The Clyman API utilizes either JSON or Protocol Buffers, based on what the server is configured to process. In either case, the field names and message structure remains the same. This document will focus on the JSON API, but with this knowledge and the DVS Interface Protocol Buffer files, the use of the Protocol Buffer API should be equally clear.

Response Messages follow the same format as inbound messages, with a few additional fields.

To start with, here is an example JSON message which will create a single object:

{

“msg_type”: 0,

“operation”: 10,

“transaction_id”: “12352”,

“num_records”: 1,

“objects”: [

{

“key”: “ABCDEF131”,

“name”: “Test Object8”,

“type”: “Mesh”,

“subtype”: “Cube”,

“owner”: “123”,

“scene”: “DEFGHI8”,

“frame”: 1,

“timestamp”: 123456789,

“translation”: [0, 0, 0],

“quaternion_rotation”: [0, 0, 0, 0],

“euler_rotation”: [0, 0, 0],

“scale”: [1, 1, 1],

“assets”: [“Asset_4”]

}

]

}

Let’s take a look at the individual fields.

Object List

The Object List is the highest level wrapper in the API. It only contains 6 keys, one of which is an array of objects.

• msg_type – 0 for create, 1 for update, 2 for retrieve, 3 for delete, 4 for query, 5 to acquire a Device Lock, and 6 to release a Device Lock. The message type applies to all objects in the objects array.
• operation - An optional field used during updates to specify the type of operation. 10 is append, and 11 is remove. Remove operations can be used to remove assets from an object.
• err_code - An integer error code for the response, full list of codes can be found in the appendix.
• err_msg - A string error message for the response, will not be present when no error was encountered.
• transaction_id – An ID to distinguish a transaction within a larger network of applications
• num_records – This lets us give Clyman a maximum number of values to return from a query
• objects – An array containing objects

Object

A single Object (or Obj3, from here on out), is represented by a single element of the array from the “objects” key of the object list.

• key – Obj3 Key value (UUID)
• name – Name of the Obj3
• type – A string type of the Obj3. Normal types are ‘Mesh’, ‘Curve’, etc. However, no limitations are placed on what types may be entered.
• subtype – Similar to type, meant to differentiate between different types and allow for use of basic primitives which can be communicated from device to device very quickly. For example, ‘Cube’, ‘Sphere’, etc.
• owner – Identifier for the owner of the Obj3
• scene – ID For the Scene containing the object
• frame – The frame of the Object transformations
• timestamp – The timestamp of the Object transformations
• translation – X, Y, and Z values for the translation of the object from it’s origin
• euler_rotation – X, Y, and Z values for the local rotation of the object about the respective axis, in radians
• quaternion_rotation - W, X, Y, and Z values for the local quaternion rotation of the object, in radians
• scale – X, Y, and Z values for the scaling of the object
• assets – An Array of identifiers for “assets”, which should be downloaded by users in order to view the object.

Field Mapping

Field	Data Type	Create	Get	Update	Delete	Query	Lock	Unlock	Overwrite
msg_type	Integer	X	X	X	X	X	X	X	X
operation	Integer			*
transaction_id	String	*	*	*	*	*	*	*	*
num_records	String					*
key	String		X	*	X	*	*	*	*
name	String	X		*		*	*	*	*
type	String	*		*		*	*	*
subtype	String	*		*		*	*	*
owner	String	*		*		*	*	*
scene	String	X		*		*	*	*	*
frame	Integer	*		*		*	*	*	*
timestamp	Integer	*		*		*	*	*	*
translation	Array - Double	X		*		*	*	*	*
euler_rotation	Array - Double	X		*		*	*	*	*
quaternion_rotation	Array - Double	X		*		*	*	*	*
scale	Array - Double	X		*		*	*	*	*
assets	Array - String	X		*			*	*

X – Required

* - Optional

Message Types

Object Create

Create a new Obj3. Returns a unique key for the object.

Object Retrieve

The object retrieve message will retrieve an object by key, and return the full object

Object Update

Object updates can be used to either update basic object attributes (name, type, etc), or to apply transformations to the object. Transformations will be applied in the order that they are received.

Object Destroy

Destroy an existing Obj3 by key. Basic success/failure response.

Object Query

This will query objects by attributes other than their keys

Device Lock Acquire

Subset of Object Update, uses ‘owner’ field as the key to acquire a lock on an object. This ensures that no other devices update the object, until the lock is released.

Device Lock Release

Subset of Object Update, uses ‘owner’ field as the key to release a lock on an object.

Object Overwrite

An Object Overwrite is designed to be a high-speed update, primarily used for live feeds. Rather than sending in transformations from the current state of the object, as in the Object Update message, here the Object sends the current total state of the object, rather than the difference. This completely overwrites the transform information of the object, and streams that information out to other devices via Apache Kafka.

This message can utilize either a Key or a Name-Scene combination to perform the overwrite.

Appendix A: JSON Message Samples

Inbound

Object Create

{

“msg_type”: 0, “transaction_id”: “12354”, “num_records”: 1, “objects”: [

{

“key”: “ABCDEF133”, “name”: “Test Object10”, “type”: “Mesh”, “subtype”: “Cube”, “owner”: “123”, “scene”: “DEFGHI10”, “translation”: [0, 0, 0], “quaternion_rotation”: [0, 0, 0, 0], “euler_rotation”: [0, 0, 0], “scale”: [1, 1, 1], “assets”: [“Asset_5”]

}

]

}

Object Retrieve

{

“msg_type”: 2, “transaction_id”: “123464”, “num_records”: 256, “objects”: [

{

“key”: “59ab6e44ac48b7000148c86a”

}

]

}

Object Update

{

“msg_type”: 1, “operation”: 10, “transaction_id”: “123464”, “num_records”: 1, “objects”: [

{

“key”: “59ab6e44ac48b7000148c86a”, “name”: “Test Object 123464”, “type”: “Curve”, “subtype”: “Sphere”, “owner”: “456”, “scene”: “DEFGHIJ123464”, “translation”: [0, 0, 1], “quaternion_rotation”: [0, 0, 0, 0], “euler_rotation”: [0, 0, 0], “scale”: [1, 1, 2], “assets”: [“Asset_5”]

}

]

}

Object Overwrite

{

“msg_type”: 1, “operation”: 10, “transaction_id”: “123464”, “num_records”: 1, “objects”: [

{

“key”: “59ab6e44ac48b7000148c86a”, “name”: “Test Object 123464”, “scene”: “DEFGHIJ123464”, “translation”: [0, 0, 1], “quaternion_rotation”: [0, 0, 0, 0], “euler_rotation”: [3.14, 0, 0], “scale”: [1, 1, 2]

}

]

}

Object Destroy

{

“msg_type”: 3, “transaction_id”: “123463”, “num_records”: 1, “objects”: [

{

“key”: “59ab6e44ac48b7000148c869”

}

]

}

Object Query

{

“msg_type”: 4, “transaction_id”: “123463”, “num_records”: 1, “objects”: [

{

“name”: “Test Object 123463”

}, {

“name”: “Test Object 123464”

}

]

}

Object Lock

{

“msg_type”: 5, “transaction_id”: “123465”, “num_records”: 1, “objects”: [

{

“key”: “59ab6e44ac48b7000148c86b”, “name”: “Test Object 123465”, “type”: “Mesh”, “subtype”: “Cube”, “owner”: “10”, “scene”: “DEFGHIJ123465”, “translation”: [0, 0, 1], “quaternion_rotation”: [0, 0, 0, 0], “euler_rotation”: [0, 0, 0], “scale”: [1, 1, 2], “assets”: [“Asset_5”]

}

]

}

Object Unlock

{

“msg_type”: 6, “transaction_id”: “123465”, “num_records”: 1, “objects”: [

{

“key”: “59ab6e44ac48b7000148c86b”, “name”: “Test Object 123465”, “type”: “Mesh”, “subtype”: “Cube”, “owner”: “10”, “scene”: “DEFGHIJ123465”, “translation”: [0, 0, 1], “quaternion_rotation”: [0, 0, 0, 0], “euler_rotation”: [0, 0, 0], “scale”: [1, 1, 2], “assets”: [“Asset_5”]

}

]

}

Response

Object Create

{

“msg_type”:0, “err_code”:100, “num_records”:1, “objects”:[

{

“key”:”59ab6e44ac48b7000148c86b”, “transform”:[1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0]

}

]

}

Object Update

{

“msg_type”:1, “err_code”:100, “num_records”:1, “objects”:[

{

“key”:”59ab6e44ac48b7000148c86b”, “name”:”Test Object 123465”, “scene”:”DEFGHIJ123465”, “type”:”Mesh”, “subtype”:”Cube”, “owner”:”456”, “transform”:[1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,2.0,2.0,0.0,0.0,0.0,1.0], “assets”: [“Asset_5”]

}

]

}

Object Overwrite

{“msg_type”:7,”err_code”:100,”num_records”:0,”objects”:[]}

Object Retrieve

{

“msg_type”:2, “err_code”:100, “num_records”:1, “objects”:[

{

“key”:”59ab6e44ac48b7000148c869”, “name”:”Test Object8”, “scene”:”DEFGHI8”, “type”:”Mesh”, “subtype”:”Cube”, “owner”:”123”, “transform”:[1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0], “assets”: [“Asset_5”]

}

]

}

Object Destroy

{

“msg\_type”:3, “err\_code”:100, “num\_records”:1, “objects”:[

{

“key”:”5951dd759af59c00015b1408”, “transform”:[1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0]

}

]

}

Object Query

{

“msg_type”:4, “err_code”:100, “num_records”:2, “objects”:[

{

“name”:”Test Object 123465”, “scene”:”DEFGHIJ123465”, “type”:”Mesh”, “subtype”:”Cube”, “owner”:”456”, “transform”:[1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0], “assets”: [“Asset_5”]

}, {

“name”:”Test Object 123456”, “scene”:”DEFGHIJ123456”, “type”:”Curve”, “subtype”:”Sphere”, “owner”:”456”, “transform”:[1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,1.0], “assets”: [“Asset_5”]

}

]

}

Object Lock

{

“msg_type”:5, “err_code”:100, “num_records”:1, “objects”:[

{

“key”:”59ab6e44ac48b7000148c86b”, “name”:”Test Object 123465”, “scene”:”DEFGHIJ123465”, “type”:”Mesh”, “subtype”:”Cube”, “owner”:”10”, “transform”:[1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,4.0,6.0,0.0,0.0,0.0,1.0]

}

]

}

Object Unlock

{

“msg_type”:6, “err_code”:100, “num_records”:1, “objects”:[

{

“key”:”59ab6e44ac48b7000148c86b”, “name”:”Test Object 123465”, “scene”:”DEFGHIJ123465”, “type”:”Mesh”, “subtype”:”Cube”, “owner”:”10”, “transform”:[1.0,0.0,0.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,8.0,14.0,0.0,0.0,0.0,1.0]

}

]

}

Appendix B: Error Codes

NO_ERROR = 100

Operation was successful

ERROR = 101

An unknown error occurred

NOT_FOUND = 102

Data was not found

TRANSLATION_ERROR = 110

JSON/Protocol Buffer parsing error

PROCESSING_ERROR = 120

Unknown error occurred during processing stage of execution

BAD_MSG_TYPE_ERROR = 121

An invalid msg_type was recieved (valid values are integers from 0 to 4)

INSUFF_DATA_ERROR = 122

Insufficient data received on message to form a valid response

LOCK_EXISTS_ERROR = 123

A Device Lock Exists on the Object

Go Home