Ninja Blocks API

/rest/v0

Home

Core Concepts

REST

Device Protocols

See Also

List of Device IDs

Forums

Code

Mailing List

Block

Quick Access Via Virtual Block Token

To get you up and running quickly, we provide a virtual block token, which you can enable (and revoke), in the account settings page. This block token will allow you to create arbitrary devices under your account without activating or claiming.

Use your virtual block token exactly as you would a standard block token, i.e. pass it as an http header named X-Ninja-Token.

Block Activation Explained

Claiming / activating a block is the process of retrieving a token for a given block (identified by its node ID) that is used to link that block to a particular user.

There are two flows to block activation. First, you can request a token with user credentials. This is useful for browsers and other apps that already have a user's authorization.

The second involves a two-legged flow where a block requests a token and awaits activation (HTTP GET, does not require user authorization) and a user separately attempts to claim that block awaiting activation (HTTP POST, does require authorization). For example an Arduino might request activation, and a user then 'claims' that block via his/her browser/smartphone. The token is sent down the wire to the Arduino which then uses it in all subsequent requests.

For more information see here.

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 block Fetch all claimed blocks.
POST block Attempt to claim an unclaimed block.
GET block/:nodeId/activate Activate a block and return its token. This token should be used with all subsequent requests. Your nodeId should be a 12+ alphanumeric character identifier, ideally a unique serial number.
GET block/:nodeId Fetch a specific block's details.
DELETE block/:nodeId Unpair a block.
POST block/:nodeId/heartbeat [DEPRECATED] Send a heartbeat from this block.
POST block/:nodeId/data Send a 'data' event from this block. Typically 'data' events will be instantly actioned, as opposed to heartbeats which may be queued.
POST block/:nodeId/config Config events are intended to be meta information about a device, for example it's IP address if it were an IP camera.
GET block/:nodeId/commands Long GET that will respond with that block's commands for the duration of the request.
POST camera/:guid/snapshot Send an image that has been requested via a 'snapshot' command.

 

GET block

Returns all the blocks paired to an account.

Parameters
none

Resource URL

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

cURL Example

Fetch all of a user's blocks:

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

Sample JSON response

{
    "result": 1,
    "error": null,
    "id": 0,
    "data": {
        "STEALTHYNODE01": {
            "date_created": 1354675751000,
            "last_active": 1354765031967,
            "short_name": "Ninja Block"
        },
        "STEALTHYNODE02": {
            "date_created": 1354672575000,
            "last_active": 1354741967799,
            "short_name": "Ninja Block"
        }
    }
}

 

POST block

Attempt to claim an unclaimed block.

Parameters
nodeid
string
Required
The ID of the block you are attempting to claim. This block must be currently awaiting activation. ID's have a minimum length of 12 characters.
Example: "ASTEALTHYNODE01"

Notes

Resource URL

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

cURL Example

Attempt to claim block 123456789ABC on behalf of the user identified by their user access token

curl -X 'POST' \
     -H 'Content-Type: application/json' \
     -d '{"nodeid":"123456789ABC"}' \
     -i https://api.ninja.is/rest/v0/block?user_access_token=YOUR_API_TOKEN 

Sample JSON response

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

 

GET block/:nodeId/activate

Activate a block and return its token. This token should be used with all subsequent requests. Your nodeId should be a 12+ alphanumeric character identifier, ideally a unique serial number.

Parameters
none

Notes

Resource URL

https://api.ninja.is/rest/v0/block/:nodeId/activate

cURL Example

Listen for activation from a the block with nodeId 123456789ABC:

curl -i https://api.ninja.is/rest/v0/block/123456789ABC/activate

Sample JSON response

{
  "token": "1c0c8929-3318-411d-96e0-36fb7872ea5c"
}

 

GET block/:nodeId

Returns data about the specified block.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/block/:nodeId

cURL Example

Fetch one block's details:

curl -i https://api.ninja.is/rest/v0/block/STEALTHYNODE02?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

{
    "result": 1,
    "error": null,
    "id": 0,
    "data": {
        "date_created": 1354672575000,
        "last_active": 1354741967799,
        "short_name": "Ninja Block"
    }
}

 

DELETE block/:nodeId

Unpair a block.

Parameters
none

Notes

Resource URL

https://api.ninja.is/rest/v0/block/:nodeId

cURL Example

Unpair the block 'STEALTHYNODE02':

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

Sample JSON response

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

 

POST block/:nodeId/heartbeat

Deprecated

Send a heartbeat from this block.
Important: the request body takes the form of an array of objects, whose parameters are outlined below.

Heartbeat events are intended to be values to be analyzed in due course. For example, a temperature reading should be part of a 'heartbeat' event, whereas a button press should be a 'data' event.

Each Array Element Parameters
G
string
Required
The port/channel number the device is located on.
Example: 0
V
number
Required
The Vendor ID of the device.
Example: "0"
D
number
Required
The device ID.
Example: 11
DA
string
Required
The data value that this device is reporting.
Example: "-1"

Notes

Resource URL

https://api.ninja.is/rest/v0/block/:nodeId/heartbeat

cURL Example

Send a heartbeat from a temperature device 20 degrees C and report RGB LED device as purple. Note that heartbeats contain an array of device data, it must be submitted as an array even if there is only a single device.

curl -X 'POST' \
     -H 'X-Ninja-Token: YOUR_BLOCK_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '[{"G":"0","V":0,"D":9,"DA":"20"},{"G":"0","V":0,"D":1000,"DA":"FF00FF"}]' \
     -i https://api.ninja.is/rest/v0/block/123456789ABC/heartbeat 

Sample JSON response

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

 

POST block/:nodeId/data

Send a data event from this block.

Data events are intended to be values to be actioned immediately. For example, a button press should be a 'data' event, whereas a temperature reading should be part of a 'heartbeat' event

Parameters
G
string
Required
The port/channel the device is located on.
Example: 0
V
number
Required
The Vendor ID of the device.
Example: "0"
D
number
Required
The device ID.
Example: 11
DA
string
Required
The data value that this device is reporting.
Example: "-1"

Notes

Resource URL

https://api.ninja.is/rest/v0/block/:nodeId/data

cURL Example

curl -X 'POST' \
     -H 'X-Ninja-Token: YOUR_BLOCK_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"G":"0","V":0,"D":5,"DA":"1"}' \
     -i https://api.ninja.is/rest/v0/block/123456789ABC/data 

Sample JSON response

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

 

POST block/:nodeId/config

Send a config event from this block.

Config events are intended to be meta information about a device, for example it's IP address if it were an IP camera, whether its plugged in or not, etc.

Parameters
G
string
Required
The port/channel the device is located on.
Example: 0
V
number
Required
The Vendor ID of the device.
Example: "0"
D
number
Required
The device ID.
Example: 11
type
string
Required
The type of the config event. Currently in our dashboard we support "UNPLUG" & "PLUGIN", however this can be anything.
Example: "PLUGIN"

Notes

Resource URL

https://api.ninja.is/rest/v0/block/:nodeId/config

cURL Example

curl -X 'POST' \
     -H 'X-Ninja-Token: YOUR_BLOCK_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"G":"0","V":0,"D":5,"type":"UNPLUG"}' \
     -i https://api.ninja.is/rest/v0/block/123456789ABC/config 

Sample JSON response

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

 

GET block/:nodeId/commands

Long GET that will respond with a the requested block's commands.

Parameters
none

Notes

Resource URL

https://api.ninja.is/rest/v0/block/:nodeId/commands

cURL Example

Await a command sent to this block:

curl -H 'X-Ninja-Token: YOUR_BLOCK_TOKEN' \
     -H 'Content-Type: application/json' \
     -i https://api.ninja.is/rest/v0/block/123456789ABC/commands

Sample JSON response

{"DEVICE":[{"G":"0","V":0,"D":1000,"DA":"FFFFFF"}]}

 

POST camera/:guid/snapshot

Send an image that has been requested via a 'snapshot' command.

Parameters
none

Notes

Resource URL

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