Scene API

A Scene is a group of Objects associated to a particular Latitude and Longitude. Examples of Scenes include levels in a video game, rooms in a house, and shots in a movie. This API exposes CRUD and Query operations for Scenes.

When authentication is active, scenes are associated to the user that creates them and can be public or private. Users can only interact with scenes that are either public, or that they own.

Scene Creation

PUT /v1/scene/(key)

Create a new scene with key key.

Request Headers:
 
Status Codes:

http

PUT /v1/scene/key HTTP/1.1
Host: localhost:5885
Content-Type: application/json

{
  "scenes": [
    {
      "name": "testScene",
      "region":"US-MD",
      "latitude":124,
      "longitude":122,
      "assets":["TestAsset10"],
      "tags":["Testing2"],
      "public": true
    }
  ]
}

curl

curl -i -X PUT http://localhost:5885/v1/scene/key -H 'Content-Type: application/json' --data-raw '{"scenes": [{"name": "testScene", "tags": ["Testing2"], "region": "US-MD", "longitude": 122, "latitude": 124, "public": true, "assets": ["TestAsset10"]}]}'

response

HTTP/1.1 200 OK
Location: http://localhost:5885/v1/scene/key
Content-Type: application/json

{
  "num_records":1,
  "scenes":[{"key":"jklmnop"}]
}

Scene Update

POST /v1/scene/(key)

Update an existing scene with key key. This executes a full overwrite of any fields present in the message, and triggers Object Change Streams.

Request Headers:
 
Status Codes:

http

POST /v1/scene/key HTTP/1.1
Host: localhost:5885
Content-Type: application/json

{
  "scenes": [
    {
      "name": "testScene",
      "region":"US-MD",
      "latitude":124,
      "longitude":122,
      "assets":["TestAsset10"],
      "tags":["Testing2"]
    }
  ]
}

curl

curl -i -X POST http://localhost:5885/v1/scene/key -H 'Content-Type: application/json' --data-raw '{"scenes": [{"name": "testScene", "tags": ["Testing2"], "region": "US-MD", "longitude": 122, "latitude": 124, "assets": ["TestAsset10"]}]}'

response

HTTP/1.1 200 OK
Location: http://localhost:5885/v1/scene/key
Content-Type: application/json

{
  "num_records":1,
  "scenes":[{"key":"jklmnop"}]
}

Scene Retrieval

GET /v1/scene/(key)

Retrieve scene information for scene key. This includes name, region, tags, latitude, and longitude.

Status Codes:

http

GET /v1/scene/key HTTP/1.1
Host: localhost:5885

curl

curl -i http://localhost:5885/v1/scene/key

response

HTTP/1.1 200 OK
Location: http://localhost:5885/v1/scene/key
Content-Type: application/json

{
    "msg_type": 2,
    "err_code": 100,
    "num_records": 1,
    "start_record": 0,
    "scenes": [
        {
            "key": "123",
            "name": "testScene",
            "region": "us-ga",
            "latitude": 100,
            "active": true,
            "longitude": 100,
            "distance": 0,
            "assets": [
                "asset1"
            ],
            "tags": [
                "tag1"
            ],
            "devices": []
        }
    ]
}

Scene Deletion

DELETE /v1/scene/(key)

Delete a scene.

CAUTION: This will delete all information associated to a scene, including all registered devices.

Status Codes:

http

DELETE /v1/scene/key HTTP/1.1
Host: localhost:5885

curl

curl -i -X DELETE http://localhost:5885/v1/scene/key

Scene Query

POST /v1/scene/query

Find scenes by one or more attributes, including distance.

The fields ‘latitude’, ‘longitude’, and ‘distance’ should always appear together if present. The distance provided is taken in kilometers.

Multiple scenes can be passed in the scene_list attribute, and the return value will be the sum of the results from each query.

Request Headers:
 
Status Codes:

http

POST /v1/scene/query HTTP/1.1
Host: localhost:5885
Content-Type: application/json

{
  "scenes":[
    {
      "name":"test",
      "region":"US-MD",
      "latitude":124,
      "longitude":122,
      "assets":["TestAsset10"],
      "tags":["Testing2"]
    }
  ]
}

curl

curl -i -X POST http://localhost:5885/v1/scene/query -H 'Content-Type: application/json' --data-raw '{"scenes": [{"name": "test", "tags": ["Testing2"], "region": "US-MD", "longitude": 122, "latitude": 124, "assets": ["TestAsset10"]}]}'

response

HTTP/1.1 200 OK
Location: http://localhost:5885/v1/scene/query
Content-Type: application/json

{
"num_records":1,
  "scenes":[
    {
    "key":"jklmnop",
    "name":"TestScene10",
    "region":"US-MD",
    "latitude":124.0,
    "longitude":122.0,
    "tags":["test","test2"],
    "asset_ids":["asset1","asset2"]
    }
  ]
}