An Object is represented by a transformation matrix representing it’s position in 3-space, as well as a collection of Assets (Mesh files, Texture files, Shader scripts, etc.), and potentially a frame and/or timestamp. This API exposes CRUD and Query operations for Objects.
Objects are meant to be interacted with by individual devices, and these changes will be streamed to other devices via the Events API. In addition, Create and Update messages sent to the HTTP API are converted to events and streamed out to registered devices.
POST
/v1/object/
¶Create a new object.
Request Headers: | |
---|---|
|
|
Status Codes: |
|
POST /v1/object HTTP/1.1
Host: localhost:8768
Content-Type: application/json
{
"msg_type": 0,
"objects": [
{
"name": "Test Object 123464",
"type": "Curve",
"subtype": "Sphere",
"owner": "",
"assets": ["Asset_5"],
"scene": "testScene",
"actions": [
{
"name": "testAction",
"description": "this is a description",
"keyframes": [
{
"frame": 0,
"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],
"translation_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
],
"rotation_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
],
"scale_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
]
}
]
}
]
}
]
}
curl -i -X POST http://localhost:8768/v1/object -H 'Content-Type: application/json' --data-raw '{"msg_type": 0, "objects": [{"name": "Test Object 123464", "scene": "testScene", "actions": [{"name": "testAction", "keyframes": [{"rotation_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}], "frame": 0, "translation_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}], "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], "scale_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}]}], "description": "this is a description"}], "subtype": "Sphere", "owner": "", "type": "Curve", "assets": ["Asset_5"]}]}'
HTTP/1.1 200 OK
Location: http://localhost:8768/v1/object
Content-Type: application/json
{
"num_records":1,
"objects":[{"key":"jklmnop"}]
}
POST
/v1/object/{key}
¶Update an existing object.
Request Headers: | |
---|---|
|
|
Status Codes: |
|
POST /v1/object/{key} HTTP/1.1
Host: localhost:8768
Content-Type: application/json
{
"msg_type": 0,
"objects":[
{
"name": "Test Object 123464",
"type": "Curve",
"subtype": "Sphere"
}
]
}
curl -i -X POST 'http://localhost:8768/v1/object/{key}' -H 'Content-Type: application/json' --data-raw '{"msg_type": 0, "objects": [{"subtype": "Sphere", "type": "Curve", "name": "Test Object 123464"}]}'
HTTP/1.1 200 OK
Location: http://localhost:8768/v1/object/{key}
Content-Type: application/json
{
"num_records":1,
"objects":[{"key":"jklmnop"}]
}
GET
/v1/object/
(key)¶Get an object details in JSON Format.
Status Codes: |
|
---|
GET /v1/object/{key} HTTP/1.1
Host: localhost:8768
curl -i 'http://localhost:8768/v1/object/{key}'
DELETE
/v1/object/
(key)¶Delete an object.
Status Codes: |
|
---|
DELETE /v1/object/{key} HTTP/1.1
Host: localhost:8768
curl -i -X DELETE 'http://localhost:8768/v1/object/{key}'
GET
/v1/object/query
¶Query for objects which match the input JSON. This will only return as many records as specified in the field ‘num_records’.
Status Codes: |
|
---|
POST /v1/object/query HTTP/1.1
Host: localhost:8768
Content-Type: application/json
{
"objects":[
{
"name":"test",
"assets":["TestAsset10"]
}
]
}
curl -i -X POST http://localhost:8768/v1/object/query -H 'Content-Type: application/json' --data-raw '{"objects": [{"name": "test", "assets": ["TestAsset10"]}]}'
GET
/v1/object/{key}/lock
¶A lock allows a single client to obtain ‘ownership’ of an object. This is an atomic operation, and is guaranteed to return a lock to one and only one client who requests it. Keep in mind, however, that no checks are performed within CLyman to verify that the object’s owner is the only one updating it, it is the responsibility of the client to obtain a lock prior to making updates.
Status Codes: |
|
---|---|
Query Parameters: | |
|
GET /v1/object/{key}/lock?device=123 HTTP/1.1
Host: localhost:8768
curl -i 'http://localhost:8768/v1/object/{key}/lock?device=123'
DELETE
/v1/object/{key}/lock
¶Unlocking allows a client to release ‘ownership’ of an object. This is an atomic operation, and no additional locks will be granted on a locked object until this method is called by the owner.
Status Codes: |
|
---|---|
Query Parameters: | |
|
DELETE /v1/object/{key}/lock?device=123 HTTP/1.1
Host: localhost:8768
curl -i -X DELETE 'http://localhost:8768/v1/object/{key}/lock?device=123'
POST
/v1/object/{key}/action
¶An action is a named set of keyframes, each holding the position of the object at that frame. This endpoint allows creation of a new action against an existing object.
Status Codes: |
|
---|
POST /v1/object/{key}/action HTTP/1.1
Host: localhost:8768
Content-Type: application/json
{
"name": "testAction",
"description": "this is a description",
"keyframes": [
{
"frame": 0,
"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],
"translation_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
],
"rotation_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
],
"scale_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
]
}
]
}
curl -i -X POST 'http://localhost:8768/v1/object/{key}/action' -H 'Content-Type: application/json' --data-raw '{"description": "this is a description", "keyframes": [{"rotation_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}], "frame": 0, "translation_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}], "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], "scale_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}]}], "name": "testAction"}'
POST
/v1/object/{key}/action/{name}
¶This endpoint allows for updating fields within an action.
Status Codes: |
|
---|
POST /v1/object/{key}/action/{name} HTTP/1.1
Host: localhost:8768
Content-Type: application/json
{
"name": "testAction",
"description": "this is another description"
}
curl -i -X POST 'http://localhost:8768/v1/object/{key}/action/{name}' -H 'Content-Type: application/json' --data-raw '{"description": "this is another description", "name": "testAction"}'
DELETE
/v1/object/{key}/action/{name}
¶This endpoint allows for removing actions from an object.
Status Codes: |
|
---|
DELETE /v1/object/{key}/action/{name} HTTP/1.1
Host: localhost:8768
curl -i -X DELETE 'http://localhost:8768/v1/object/{key}/action/{name}'
POST
/v1/object/{key}/action/{name}/keyframe
¶This endpoint allows for adding keyframes to existing actions.
Status Codes: |
|
---|
POST /v1/object/{key}/action/{name}/keyframe HTTP/1.1
Host: localhost:8768
Content-Type: application/json
{
"frame": 10,
"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],
"translation_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
],
"rotation_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
],
"scale_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
]
}
curl -i -X POST 'http://localhost:8768/v1/object/{key}/action/{name}/keyframe' -H 'Content-Type: application/json' --data-raw '{"frame": 10, "rotation_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}], "scale_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}], "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], "translation_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}]}'
POST
/v1/object/{key}/action/{name}/keyframe/{frame}
¶This endpoint allows for updating elements within a keyframe.
Status Codes: |
|
---|
POST /v1/object/{key}/action/{name}/keyframe/{frame} HTTP/1.1
Host: localhost:8768
Content-Type: application/json
{
"frame": 10,
"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],
"translation_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
],
"rotation_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
],
"scale_handle":[
{"left_type":"test","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0},
{"left_type":"","left_x":0.0,"left_y":0.0,"right_type":"","right_x":0.0,"right_y":0.0}
]
}
curl -i -X POST 'http://localhost:8768/v1/object/{key}/action/{name}/keyframe/{frame}' -H 'Content-Type: application/json' --data-raw '{"frame": 10, "rotation_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}], "scale_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}], "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], "translation_handle": [{"left_type": "test", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}, {"left_type": "", "left_x": 0.0, "left_y": 0.0, "right_x": 0.0, "right_y": 0.0, "right_type": ""}]}'
DELETE
/v1/object/{key}/action/{name}/keyframe/{frame}
¶This endpoint removes a keyframe from an existing action.
Status Codes: |
|
---|
DELETE /v1/object/{key}/action/{name}/keyframe/{frame} HTTP/1.1
Host: localhost:8768
curl -i -X DELETE 'http://localhost:8768/v1/object/{key}/action/{name}/keyframe/{frame}'
PUT
/v1/object/{object_key}/asset/{asset_key}
¶We can add an asset to an object easily with this API.
Status Codes: |
|
---|
PUT /v1/object/{object_key}/asset/{asset_key} HTTP/1.1
Host: localhost:8768
curl -i -X PUT 'http://localhost:8768/v1/object/{object_key}/asset/{asset_key}'
DELETE
/v1/object/{object_key}/asset/{asset_key}
¶We can remove an asset from an object easily with this API.
Status Codes: |
|
---|
DELETE /v1/object/{object_key}/asset/{asset_key} HTTP/1.1
Host: localhost:8768
curl -i -X DELETE 'http://localhost:8768/v1/object/{object_key}/asset/{asset_key}'