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",
    "links": {
        "features": "/features",
        "commands": "/commands",
        "events": "/events",
        "subscriptions": "/subscriptions"
    }
}
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:

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

[
    {
        "id": "switch_1",
        "type": "SwitchBinary",
        "name": "My Switch",
        "description": "This is a switch",
        "links": {
            "detail": "/features/switch_1",
            "commands": "/features/switch_1/commands",
            "events": "/features/switch_1/events",
            "subscriptions": "/features/switch_1/subscriptions"
        }
    },
    {
        "id": "switch_2",
        "type": "SwitchMultiLevel",
        "name": "My Dimmer"
        "description": "This is a dimmable switch",
        "links": {
            "detail": "/features/switch_2",
            "commands": "/features/switch_2/commands",
            "events": "/features/switch_2/events",
            "subscriptions": "/features/switch_2/subscriptions"
        }
    }
]
Response JSON Array of Objects:
 
  • id (string) – The feature id
  • name (string) – The feature name
  • type (string) – The feature type
  • description (string) – The feature description
Status Codes:
GET /features/{feature_id}

Get feature details

Example request:

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

Example response:

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

{
    "id": "switch_1",
    "type": "SwitchBinary",
    "name": "My Switch",
    "description": "This is a switch",
    "links": {
        "features": "/features",
        "commands": "/features/switch_1/commands",
        "events": "/features/switch_1/events",
        "subscriptions": "/features/switch_1/subscriptions"
    }
}
Response JSON Object:
 
  • id (string) – The feature id
  • name (string) – The feature name
  • type (string) – The feature type
  • description (string) – The feature description
Status Codes:

Commands

POST /commands

Create a new command

Example request:

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

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

Example response:

HTTP/1.1 200 OK
Content-Type: text/javascript
Request JSON Object:
 
  • command_type (string) – The type of command
  • feature_id (string) – The id of the target feature
  • data (object) – The data for the command
Status Codes:

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

[
    {
        "id": "123456",
        "feature_id": "switch_1",
        "event_type": "State",
        "callback": "http://my-server.local:8000/notify",
        "timeout": 3600,
        "duration": 250,
        "calls": 10,
        "errors": 0,
        "links": {
            "feature": "/features/switch_1"
        }
    },
    {
        "id": "1234567",
        "feature_id": "switch_2",
        "event_type": "State",
        "callback": "http://my-server.local:8000/notify",
        "timeout": 3600,
        "duration": 3000,
        "calls": 200,
        "errors": 1,
        "links": {
            "feature": "/features/switch_2"
        }
    }
]
Response JSON Array of Objects:
 
  • feature_id (string) – 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:
POST /subscriptions

Create a new subscription

Example request:

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

{
    "feature_id": "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_id (string) – The target feature
  • 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: