entity/:id

Returns the default for the given entity. The id specified must be a canonical ID (i.e. an ID of the form controllerID>entityID).

Example: http://host-ip:8111/api/v1/entity/reactor_system>system

{
    "id": "system",
    "canonical_id": "reactor_system>system",
    "controller": "reactor_system",
    "type": "System",
    "name": "Reactor System",
    "lastupdate": 1636051724401,
    "capabilities": {
        "sys_system": {
            "attributes": {
                "state": {
                    "type": "bool"
                }
            },
            "actions": {
                "restart": {}
            }
        },
        "reactor_system": {
            "attributes": {
                "system_memory_size": {
                    "type": "ui8"
                },
                "system_memory_free": {
                    "type": "ui8"
                },
                "system_load": {
                    "type": "array",
                    "subtype": "real"
                },
                "system_uptime": {
                    "type": "real"
                },
                "reactor_uptime": {
                    "type": "real"
                },
                "reactor_memory_used": {
                    "type": "ui8"
                }
            }
        }
    },
    "attributes": {
        "sys_system": {
            "state": true
        },
        "reactor_system": {
            "system_memory_size": 4024152064,
            "system_memory_free": 1937788928,
            "system_load": [0.12, 0.19, 0.17],
            "system_uptime": 2084753,
            "reactor_uptime": 69820,
            "reactor_memory_used": 100483072,
            "platform": "linux",
            "arch": "arm",
            "hostname": "rpi4-1",
            "volume_reactor_logs": [101048824, 114593388, 0.881, "/home/pi/Documents/MSR/logs"],
            "volume_critical_reactor_logs": false,
            "volume_reactor_data": [101048824, 114593388, 0.881, "/home/pi/Documents/MSR/storage"],
            "volume_critical_reactor_data": false,
            "volume_reactor_base": [101048824, 114593388, 0.881, "/home/pi/Documents/MSR"],
            "volume_critical_reactor_base": false
        }
    },
    "actions": ["sys_system.restart"],
    "primary_attribute": "sys_system.state",
    "primary_value": true
}

entity/:id/attribute/:attr

Return the value of the given attribute (in attr) for the entity identifier by id. The attribute name must be fully qualified with the capability name.

Example (GET): curl -o - 'http://host-ip:8111/api/v1/entity/reactor_system>system/attribute/sys_system.state'

true

Note that the response above is a valid and complete JSON value (not all JSON starts and ends with {}); it is the representation of the value of a primitive data type (number). The response JSON may be an object or array, so more complex than the example shown above, although primitive types are the most common.

entity/:id/attribute/:attr/set

Set the value of an attribute on the named entity.

As an HTTP GET query, the URL must include a value parameter and the value to be assigned. The value will be assumed to be a string unless a type parameter is also given in the query parameters; valid values for type are string, boolean, real, int, i1, i2, i4, ui1, ui2, ui4, and json. If type is json, then value must contain a valid JSON string. Remember that HTTP GET requests are limited to 1024 bytes for the total length of the URL, so GET is not the best choice for JSON data when the length of the encoded value could be large. The parameter values must, of course, be URL-encoded.

HTTP PUT method is preferred for this API. The request body is expected to be JSON (and therefore the Content-type header should be application/json). The body is the entire value to be assigned to the attribute. The data type of the body is the data type of the value assigned to the attribute.

Example: (GET): curl -o - 'http://host-ip:8111/api/v1/entity/vera>device_123/attribute/temperature_sensor.value/set?value=22&type=real'

Example: (PUT): curl -o - -X PUT -H 'content-type: application/json' -d '22.0' 'http://host-ip:8111/api/v1/entity/vera>device_123/attribute/temperature_sensor.value/set'

entity/:id/attributes/set

Set multiple attribute values on an entity at once.

The required method, PUT, must include a JSON body describing an object, each key of which is an attribute name to be set (in capability.attribute form), and the values are the new attribute values.

Example: (PUT):

curl -o - -X PUT -H 'content-type: application/json' \
    -d '{ "temperature_sensor.value": 22.0, "temperature_sensor.units": "C" }' \
    'http://host-ip:8111/api/v1/entity/vera>device_123/attributes/set'

entity/:id/perform/:action

Perform the named action on the entity identified by id. The action must be fully-qualfied with the capability name, and the capability must be supported by the entity.

When the HTTP GET method is used, the URL must contain, as query parameters, all named values required by the action.

HTTP POST may also be used, and in this case, the POST body is expected to be of MIME type application/json and contain an object the key/value pairs of which are the parameters required by the action.

Example (GET): curl -o - 'http://host-ip:8111/api/v1/entity/vera>device_123/perform/power_switch.set?state=1'

Example (POST): curl -o - -X POST -H 'content-type: application/json' -d '{ "state": true }' 'http://host-ip:8111/api/v1/entity/vera>device_123/perform/power_switch.set'

Updated: 2022-May-21