Ninja Blocks API

/rest/v0

Home

Core Concepts

REST

Device Protocols

See Also

List of Device IDs

Forums

Code

Mailing List

Device

In the Ninja API devices are the first class citizens not Blocks. Devices are logically separate sensors and/or actuators that have a Globally Unique Identifier GUID, a Vendor ID V, a Device ID D, and a port G. Most routes use GUIDs alone to address devices, the other fields will only matter to you if you are creating devices. Ninja supplied hardware uses the convention SERIALNUMBER_G_V_D for GUIDs, which makes them easy to grok. See Core Concepts for more information.

A note on Auth

For quick dev and hacking on your own account you can use your personal API Access Token found at a.ninja.is/hacking. The cURL Examples in this document use your user_access_token. Note that when using the API with a token acquired via OAuth, the param is just access_token. See the section on authentication for more.

cURL tip: JSON responses on the command line can be very hard to read. The simplest way is to get this excellent json script and then add pipe to json | json at the end of your curl commands. Slightly more work to install but well worth the effort if you regularly work with restful APIs is the python utility HTTPie.

Resource Description
GET devices Returns the list of devices associated with the authenticating user.
GET device/:guid Fetch metadata about the specified device.
PUT device/:guid Update a device, including sending a command.
DELETE device/:guid Delete this device from the system.
GET device/:guid/data Return the historical data for the specified device.
GET device/:guid/heartbeat Return the last heartbeat for the specified device.
POST device/:guid/callback Register a new callback against this device.
GET device/:guid/callback Retrieve the current callback url registered against this device.
PUT device/:guid/callback Update an existing callback against this device.
DELETE device/:guid/callback Delete an existing callback against this device.
POST device/:guid/subdevice Create a new sub-device under this device.
PUT device/:guid/subdevice/:subdeviceId Update information about the specified sub-device.
DELETE device/:guid/subdevice/:subdeviceId Delete the specified sub-device. Note that if there are any rules attached to this sub-device they will not be deleted, but instead become ineffectual.
GET device/:guid/subdevice/:subdeviceId/data Fetch the count of the number of times the sub-device was actuated.
POST device/:deviceGuid/subdevice
/:subDeviceId/tickle/:token
Tickle a 'webhook' sub-device.
GET camera/:guid/snapshot Request an image from the specified device.

 

GET devices

Returns the list of devices associated with the authenticating user.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/devices

cURL Example

List all your devices:

curl -i https://api.ninja.is/rest/v0/devices?user_access_token=YOUR_API_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": {
    "ASTEALTHYNODE01_0301_0_30": {
        "css_class": "sensor rf digital humidity",
        "default_name": "Humidity",
        "device_type": "humidity",
        "did": "30",
        "gid": "0301",
        "has_subdevice_count": 0,
        "has_time_series": 1,
        "is_actuator": 0,
        "is_sensor": 1,
        "is_silent": 0,
        "last_data": {
            "DA": 58,
            "timestamp": 1355791804474
        },
        "meta": {},
        "node": "ASTEALTHYNODE01",
        "shortName": "Humidity",
        "subDevices": {},
        "vid": "0"
    },
    "ASTEALTHYNODE01_0301_0_31": {
        "css_class": "sensor rf digital temperature",
        "default_name": "Temperature",
        "device_type": "temperature",
        "did": "31",
        "gid": "0301",
        "has_subdevice_count": 0,
        "has_time_series": 1,
        "is_actuator": 0,
        "is_sensor": 1,
        "is_silent": 0,
        "last_data": {
            "DA": 26.6,
            "timestamp": 1355791804475
        },
        "meta": {},
        "node": "ASTEALTHYNODE01",
        "shortName": "Temperature",
        "subDevices": {},
        "vid": "0"
    },
    "ASTEALTHYNODE01_0_0_1000": {
        "css_class": "actuator cape led rgbled",
        "default_name": "On Board RGB LED",
        "device_type": "rgbled",
        "did": "1000",
        "gid": "0",
        "has_subdevice_count": 0,
        "has_time_series": 0,
        "is_actuator": 1,
        "is_sensor": 1,
        "is_silent": 0,
        "last_data": {
            "DA": "22B42B",
            "timestamp": 1355790209080
        },
        "meta": {},
        "node": "ASTEALTHYNODE01",
        "shortName": "On Board RGB LED",
        "subDevices": {},
        "vid": "0"
    },
    "ASTEALTHYNODE01_0_0_11": {
        "css_class": "sensor serial rf rf433 receiver transmitter",
        "default_name": "RF 433Mhz",
        "device_type": "rf433",
        "did": "11",
        "gid": "0",
        "has_subdevice_count": 1,
        "has_time_series": 0,
        "is_actuator": 1,
        "is_sensor": 1,
        "is_silent": 0,
        "last_data": {
            "DA": "010001010101010100010101",
            "timestamp": 1355789891324
        },
        "meta": {},
        "node": "ASTEALTHYNODE01",
        "shortName": "RF 433Mhz",
        "subDevices": {
            "6l8At": {
                "category": "rf",
                "data": "011111110001010100110000",
                "shortName": "Door Bell",
                "type": "sensor"
            }
        },
        "vid": "0"
    }
  }
}

 

GET device/:guid

Fetch metadata about the specified device.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/device/:guid

cURL Example

Fetch the meta data for the specified device:

curl -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE01_0301_0_31?user_access_token=YOUR_API_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": {
    "vid": "0",
    "did": "31",
    "device_type": "temperature",
    "default_name": "Temperature",
    "css_class": "sensor rf digital temperature",
    "is_sensor": 1,
    "is_actuator": 0,
    "is_silent": 0,
    "has_time_series": 1,
    "has_subdevice_count": 0,
    "gid": "0301",
    "guid": "ASTEALTHYNODE01_0301_0_31",
    "node": "ASTEALTHYNODE01",
    "meta": {},
    "subDevices": {},
    "last_data": {
      "DA": 25.1,
      "timestamp": 1355792584678
    }
  }
}

 

PUT device/:guid

Update a device, including sending a command.

Sending a command and updating the meta data are two distinct operations internally. If the response we send is in the affirmative, ie result = 1, then both have succeeded. However, if it is the negative, ie result = 0, then one or both of the operations failed, and you won't know which one.

We've implemented it this way for conceptual consistency. We recommend using two separate API calls if you need to handle errors.

Parameters
DA
string
Optional
The data value to send to the device.
Example: "FFFF00"
shortName
string
Optional
The meta data title of the device to update.
Example: "Living Room Webcam"

Notes

Resource URL

https://api.ninja.is/rest/v0/device/:guid

cURL Examples

Set the color of your LED to Purple:

curl -X 'PUT' \
     -H 'Content-Type: application/json' \
     -d '{ "DA" : "FF00FF" }' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_1000?user_access_token=YOUR_ACCESS_TOKEN

Rename your LED:

curl -X 'PUT' \
     -H 'Content-Type: application/json' \
     -d '{ "shortName" : "The color changing light" }' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_1000?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0
}

 

DELETE device/:guid

Delete all data about the specified device.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/device/:guid

cURL Example

Delete your LED device. Note it will be re-created on the next heart beat if plugged in:

curl -X 'DELETE' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_1000?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0
}

 

GET device/:guid/heartbeat

Return the last heartbeat for the specified device. i.e. its "current" or more accurately last reported value.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/device/:guid/heartbeat

cURL Example

Retrieve the current color of your onboard LED:

curl -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_1000/heartbeat?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": {
    "G": "0301",
    "V": 0,
    "D": 31,
    "DA": 24.9,
    "GUID": "ASTEALTHYNODE01_0301_0_31",
    "timestamp": 1355792884794,
    "node": "ASTEALTHYNODE01"
  }
}

 

GET device/:guid/data

Return the historical data for the specified device.

Parameters
from
number
Optional
Timestamp representing the beginning of the period measurements are requested for.
Example: 1343268810530
to
number
Optional
Timestamp representing the end of the period measurements are requested for.
Example: 1343268820530
interval
string
Optional
Intervals are specified by a number and a unit of time, i.e. 6hour or 1day. The supported time units are:

  • min - Minutes
  • hour - Hours
  • day - Days
  • month - Months
  • year - Years
Example: 1day
fn
string
Optional
The folding function specifies how the datapoints are reduced within each interval. The default folding function is mean which returns the mean (average). The following folding functions are supported:

  • mean - Average of all datapoints
  • sum - Sum of all datapoints
  • min - Minimum value of all datapoints
  • max - Maximum value of all datapoints
  • stddev - Standard deviation of all datapoints
  • ss - Sum of squares of all datapoints
  • count - Total number of datapoints in the DataSet
Example: count

Notes

Resource URL

https://api.ninja.is/rest/v0/device/:guid/data

cURL Example

Fetch the mean temperature in 1 day intervals for the past week:

curl -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE01_0301_0_31/data?fn=mean&interval=1day&user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": [
    {
      "t": "2012-12-18T00:00:00.000+0000",
      "v": 26.560000000000002
    }
  ]
}

 

POST device/:guid/callback

Register a new callback against this device.

Callbacks are URLs that we will POST to with this device's data, as soon as we receive it

Parameters
url
string
Required
The URL you wish to register a callback against.
Example: "http://my-app.herokuapp.com/data_callback"

Notes

Resource URL

https://api.ninja.is/rest/v0/device/:guid/callback

cURL Example

Set a new callback for a temperature sensor:

curl -X 'POST' \
     -H 'Content-Type: application/json' \
     -d '{ "url" : "http://my-app.herokuapp.com/callback_handler" }' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_9/callback?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0
}

 

GET device/:guid/callback

Retrieve the current callback url registered against this device.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/device/:guid/callback

cURL Example

Retrieve the current callback for the temperature sensor:

curl -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_9/callback?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": {
    "url": "http://my-app.herokuapp.com/another_handler"
  }
}

 

PUT device/:guid/callback

Update an existing callback against this device.

Parameters
url
string
Required
The URL you wish to update this callback to.
Example: "http://my-app.herokuapp.com/data_callback"

Resource URL

https://api.ninja.is/rest/v0/device/:guid/callback

cURL Example

Update the temperature callback:

curl -X 'PUT' \
     -H 'Content-Type: application/json' \
     -d '{ "url" : "http://my-app.herokuapp.com/different_temp_handler" }' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_9/callback?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0
}

 

DELETE device/:guid/callback

Delete an existing callback against this device.

Once this request returns, the system will no longer POST to the previous callback.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/device/:guid/callback

cURL Example

Retrieve the current callback for the temperature sensor:

curl -X 'DELETE' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_9/callback?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0
}

 

POST device/:guid/subdevice

Create a new sub-device associated with the specified device and return a unique ID within the device.

Sub-devices allow you to store different values against one device. For example, various mobile numbers against the SMS device, different 'webhook' actuators against the 'webhook' device, and different RF binary values against the RF433MHz device.

Please note that the different categories of sub-devices may return different data. For example, the create 'webhook' 'sensor' sub-device call will return a token that is used as part of the URL to 'tickle' it, whereas most others will just return the id of the sub-device.

Webhooks Note: to enable webhooks the user must have added the Webhooks device, which is done via the "Services" tab in the settings page, or by a GET to https://api.ninja.is/auth/webhook. For more information about Webhooks see our GitHub wiki for examples.

Parameters
category
string
Required
The category of sub-device. Allowed: "rf", "webhook", "sms". This determines the behavior associated with the sub-device, and MUST correspond to the type of device used against.
Example: "rf"
type
string
Required
The type of sub-device, whether it is an actuator or a sensor. Allowed: "actuator" or "sensor"
Example: "actuator"
shortName
string
Required
The short name describing the sub-device.
Example: "Lamp On"
data
string
Optional
Data to be stored in the sub-device
Example: "001100110011000011100101"
url
string
Optional
URL to store in the sub-device in a webhook actuator (category must be 'webhook' and type must be 'actuator').
Example: "http://example.com/webhook/to/hit"

Notes

Resource URL

https://api.ninja.is/rest/v0/device/:guid/subdevice

cURL Webhook Sensor Example

Create a webhook sensor that can be actuated via a tickle:

curl -X 'POST' \
     -H 'Content-Type: application/json' \
     -d '{ "category" : "webhook", "type":"sensor", "shortName":"My Sensor Webhook" }' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_9/subdevice?user_access_token=YOUR_ACCESS_TOKEN

Sample Webhook Sensor JSON Response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": {
    "id":"LA9EJ",
    "token": "1c0c8929-3318-411d-96e0-36fb7872ea5d"
  }
}

cURL RF Actuator Example

Create a RF actuator:

curl -X 'POST' \
     -H 'Content-Type: application/json' \
     -d '{ "category" : "rf", "type":"actuator", "shortName":"My RF Actuator" }' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_9/subdevice?user_access_token=YOUR_ACCESS_TOKEN

Sample RF Actuator JSON Response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": {
    "id":"MB0FH"
  }
}

 

PUT device/:guid/subdevice/:subdeviceId

Update information about the specified sub-device.

Parameters
category
string
Optional
The category of sub-device. Allowed: "rf", "webhook", "sms". This determines the behaviour associated with the sub-device, and MUST correspond to the type of device used against.
Example: "rf"
type
string
Optional
The type of subdevice, whether it is an actuator or a sensor. Allowed: "actuator" or "sensor"
Example: "actuator"
shortName
string
Optional
The short name describing the sub-device.
Example: "Lamp Off"
data
string
Optional
The data to be stored against the subdevice.
Example: "100010100010101011010110"
url
string
Optional
URL to store in the sub-device in a webhook actuator (category must be 'webhook' and type must be 'actuator').
Example: "http://example.com/webhook/to/hit"

Resource URL

https://api.ninja.is/rest/v0/device/:guid/subdevice/:subdeviceId

cURL Example

Update the data stored in the specified sub-device:

curl -X 'PUT' \
     -H 'Content-Type: application/json' \
     -d '{ "data" : "100010100010101011010110" }' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_11/subdevice/MB0FH?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0
}

 

DELETE device/:guid/subdevice/:subdeviceId

Delete the specified sub-device. Note that if there are any rules attached to this sub-device they will not be deleted, but instead become ineffectual.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/device/:guid/subdevice/:subdeviceId

cURL Example

Delete the specified sub-device:

curl -X 'DELETE' \
     -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE_0_0_11/subdevice/MB0FH?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0
}

 

GET device/:guid/subdevice/:subdeviceId/data

Fetch the count of the number of times the sub-device was actuated.

Parameters
from
number
Optional
Timestamp representing the beginning of the period measurements are requested for.
Example: 1343268810530
to
number
Optional
Timestamp representing the end of the period measurements are requested for.
Example: 1343268820530
interval
string
Optional
Intervals are specified by a number and a unit of time, i.e. 6hour or 1day. The supported time units are:

  • min - Minutes
  • hour - Hours
  • day - Days
  • month - Months
  • year - Years
Example: 1day

Notes

Resource URL

https://api.ninja.is/rest/v0/device/:guid/subdevice/:subdeviceId/data

cURL Example

Fetch the counts in 1 minute interval of this sub-device:

curl -i https://api.ninja.is/rest/v0/device/ASTEALTHYNODE01_0_0_11/subdevice/MA9EJ/data?interval=1min&user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": [
    {
      "t": "2012-06-28T01:49:00.000+0000",
      "v": 5
    },
    {
      "t": "2012-06-28T01:50:00.000+0000",
      "v": 2
    },
    {
      "t": "2012-06-28T01:51:00.000+0000",
      "v": 8
    },
    {
      "t": "2012-06-28T01:52:00.000+0000",
      "v": 25
    },
    {
      "t": "2012-06-28T01:53:00.000+0000",
      "v": 3
    },
    {
      "t": "2012-06-28T01:54:00.000+0000",
      "v": 6
    }
  ]
}

 

POST device/:deviceGuid/subdevice/:subDeviceId/tickle/:token

'Tickle' a 'webhook' sub-device. By calling this, you effectively 'actuate' the device. This is especially useful when used with the corresponding rule precondition handler.

Parameters
none

Notes

Resource URL

https://api.ninja.is/rest/v0/device/:deviceGuid/subdevice/:subDeviceId/tickle/:token

cURL Example

Fetch the counts in 1 minute interval of this sub-device:

curl -X 'POST' \
     -i https://api.ninja.is/rest/v0/device/WEBHOOK_0_0_108/subdevice/LA9EJ/tickle/1c0c8929-3318-411d-96e0-36fb7872ea5d

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0
}

 

GET camera/:guid/snapshot

Request an image from the specified device. Returns a jpeg piped straight from the webcam.

Parameters
none

Notes

Resource URL

https://stream.ninja.is/rest/v0/camera/:guid/snapshot
Note: this call is to stream.ninja.is.

cURL Example

curl -i https://stream.ninja.is/rest/v0/camera/ASTEALTHYNODE01_0_0_1004/snapshot?user_access_token=YOUR_ACCESS_TOKEN

Sample cURL Response

HTTP/1.1 200 OK
Cache-Control: no-store, no-cache, must-revalidate, pre-check=0, post-check=0, max-age=0
Content-Type: image/jpeg
Date: Tue, 18 Dec 2012 03:56:19 GMT
Expires: Mon, 3 Jan 2000 12:34:56 GMT
Pragma: no-cache
Server: MJPG-Streamer/0.2
transfer-encoding: chunked
Connection: keep-alive

[Binary content of snapshot]

Sample Binary Response