RAD API Specification v1.0¶

Features¶

The list of supported device Features in this version are as follows:

SwitchBinary
SwitchMultiLevel
SwitchBinaryColor
SwitchMultiLevelColor
Trigger
TextDisplay
SensorBinary
SensorMultiLevel

SwitchBinary: This is a simple on/off switch that can be used to control various devices that have a simple binary state.

SwitchMultiLevel: This is for switches that can change intensity (dimmable). It can be used to control any device that takes multi-level input.

SwitchBinaryColor: This is a switch that can be used to control color output as well as whether the device is powered or not.

SwitchMultiLevelColor: This is a switch that can be used to control color output as well as the level of intesity.

Trigger: This is a trigger feature that can be called without any parameters. It can be used to trigger a command or something on the device that is stateless.

TextDisplay: This feature enables sending text to devices that can display text such as LCD/LED matricies.

SensorBinary: This feature enables a sensor that has a simple binary state.

SensorContact
SensorMotion

SensorMultiLevel:

SensorTemperature
SensorHumidity

Commands¶

The list of supported Commands in this version are as follows:

Set
Get

Events¶

The list of supported Events in this version are as follows:

All
Start
State

HTTP Specification¶

GET /¶

Get info about the RAD-ESP8266 device

Example request:

GET / HTTP/1.1
Host: example.com
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "name": "My RAD Device",
    "type": "urn:rad:device:esp8266:1",
    "model": "RAD-ESP8266",
    "description": "Rad ESP8266 WiFi Module for IoT Integration",
    "serial": "ABD123",
    "UDN": "38323636-4558-4dda-9188-cd1234567890"
}

Response JSON Object:
	name (string) – The name of the ESP8266 type (string) – The full URN model (string) – description (string) – serial (string) – UDN (string) –
Status Codes:	200 OK – no error 500 Internal Server Error – error

Features¶

GET /features¶

Get a list of device features

Example request:

GET /features HTTP/1.1
Host: example.com
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "feature_name": "switch_1",
        "feature_type": "SwitchBinary"
    },
    {
        "feature_name": "switch_2",
        "feature_type": "SwitchMultiLevel"
    }
]

Response JSON Array of Objects:
	feature_name (string) – The feature name feature_type (string) – The feature type
Status Codes:	200 OK – no error 500 Internal Server Error – error

Commands¶

POST /commands¶

Create a new command

Example request:

GET /commands HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "feature_name": "switch_1",
    "command_type": "Set",
    "data": {
        "value": true
    }
}

Example response:

HTTP/1.1 200 OK
Content-Type: text/javascript

Request JSON Object:
	feature_name (string) – The name of the target feature command_type (string) – The type of command data (object) – The data for the command
Status Codes:	200 OK – no error 400 Bad Request – when form parameters are missing

Subscriptions¶

GET /subscriptions¶

Get a list of subscriptions

Example request:

GET /subscriptions HTTP/1.1
Host: example.com
Content-Type: application/json

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
    {
        "feature_name": "switch_1",
        "event_type": "State",
        "callback": "http://my-server.local:8000/notify",
        "timeout": 3600,
        "duration": 250,
        "calls": 10,
        "errors": 0
    },
    {
        "feature_name": "switch_2",
        "event_type": "State",
        "callback": "http://my-server.local:8000/notify",
        "timeout": 3600,
        "duration": 3000,
        "calls": 200,
        "errors": 1
    }
]

Response JSON Array of Objects:
	feature_name (string) – The name of the target feature event_type (string) – The type of event callback (string) – The HTTP callback timeout (int) – The timeout value duration (int) – The duration of this subscription calls (int) – The number of times the event fired errors (int) – The number of errors
Status Codes:	200 OK – no error 500 Internal Server Error – error

POST /subscriptions¶

Create a new subscription

Example request:

GET /subscriptions HTTP/1.1
Host: example.com
Content-Type: application/json

{
    "feature_name": "switch_1",
    "event_type": "State",
    "callback": "http://my-server.local:8000/notify",
    "timeout": 3600
}

Example response:

HTTP/1.1 200 OK
Content-Type: text/javascript

Request JSON Object:
	feature_name (string) – The device to use event_type (string) – The type of event to subscribe to callback (string) – The callback to call when the event occurs timeout (integer) – The timeout in seconds
Status Codes:	200 OK – no error 400 Bad Request – when form parameters are missing