Ninja Blocks API

/rest/v0

Home

Core Concepts

REST

Device Protocols

See Also

List of Device IDs

Forums

Code

Mailing List

Rule

Rules Explained

A rule is a JSON document, part of which describes a list of preconditions that will trigger a rule, and a list of actions to take if triggered. These lists are arrays and are executed serially.

Example Rule

{
  "shortName": "Nerf Gun Shooter",
  "preconditions": [
    {
      "handler": "ninjaChange",
      "params": {
        "guid": "RFID_DEVICE_GUID",
        "to": "10101000101000001010101"
      }
    }
  ],
  "actions": [
    {
      "handler": "ninjaSendCommand",
      "params": {
        "guid": "RELAY_DEVICE_GUID",
        "da": "0"
      }
    },
    {
      "handler": "sleep",
      "params": {
        "guid": "N/A",
        "sleepLength": 3000
      }
    },
    {
      "handler": "ninjaSendCommand",
      "params": {
        "guid": "RELAY_DEVICE_GUID",
        "da": "1"
      }
    },
    {
      "handler": "getNinjaSnapshot",
      "params": {
        "guid": "CAMERA_DEVICE_GUID"
      }
    },
    {
      "handler": "sendToDropbox",
      "params": {
        "guid": "DROPBOX_DEVICE_GUID"
      }
    }
  ]
}
  

Preconditions/actions documentation

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
POST rule Create a new rule.
GET rule Fetch all of a user's rules.
GET rule/:rid Fetch one rules.
PUT rule/:rid Update a rule.
DELETE rule/:rid Delete a rule.
POST rule/:rid/suspend Suspend a rule.
DELETE rule/:rid/suspend Unsuspend a rule.

 

POST rule

Create a new rule.

Parameters
shortName
string
Required
The name of your rule.
Example: "Nerf Gun Shooter"
preconditions
array
Required
Array of precondition handlers. See further documentation.
Example: [{"handler":"ninjaRangeToggle","params":{"guid":"STEALTHYNINJA_2_0_9","between":26,"and":30}}]
actions
array
Required
Array of action handlers. See further documentation.
Example: [{"handler":"sendEmail","params":{"to":"example@example.com","subject":"NINJA","body":"Hello World!","guid":"EMAIL_GUID"}}]
timeout
number
Optional
Number of seconds to wait before executing this rule again.
Example: 60

Notes

Resource URL

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

cURL Example

curl -X 'POST' \
     -H 'Content-Type: application/json' \
     -d '{"shortName":"Nerf Gun Shooter","preconditions":[{"handler":"ninjaChange","params":{"guid":"RFID_DEVICE_GUID","to":"10101000101000001010101"}}],"actions":[{"handler":"ninjaSendCommand","params":{"guid":"RELAY_DEVICE_GUID","da":"0"}},{"handler":"sleep","params":{"guid":"N/A","sleepLength":3000}},{"handler":"ninjaSendCommand","params":{"guid":"RELAY_DEVICE_GUID","da":"1"}},{"handler":"getNinjaSnapshot","params":{"guid":"CAMERA_DEVICE_GUID"}},{"handler":"sendToDropbox","params":{"guid":"DROPBOX_DEVICE_GUID"}}]}' \
     -i https://api.ninja.is/rest/v0/rule?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

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

 

GET rule

Fetch all of a users' rules.

Parameters
none

Resource URL

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

cURL Example

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

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": [
    {
      "rid": 46001,
      "preconditions": [
        {
          "handler": "ninjaChange",
          "params": {
            "to": "011111110001010100110000",
            "guid": "2712BB000675_1_0_11",
            "shortName": "Red Button"
          }
        }
      ],
      "actions": [
        {
          "handler": "ninjaSendCommand",
          "params": {
            "guid": "2712BB000675_0_0_1000",
            "da": "0000FF",
            "shortName": "Blue"
          }
        }
      ],
      "store": {},
      "suspended": false,
      "shortName": "Blue",
      "timeout": 0
    },
    {
      "rid": 89353,
      "preconditions": [
        {
          "handler": "ninjaChange",
          "params": {
            "guid": "RFID_DEVICE_GUID",
            "to": "10101000101000001010101"
          }
        }
      ],
      "actions": [
        {
          "handler": "ninjaSendCommand",
          "params": {
            "guid": "RELAY_DEVICE_GUID",
            "da": "0"
          }
        },
        {
          "handler": "sleep",
          "params": {
            "guid": "N/A",
            "sleepLength": 3000
          }
        },
        {
          "handler": "ninjaSendCommand",
          "params": {
            "guid": "RELAY_DEVICE_GUID",
            "da": "1"
          }
        },
        {
          "handler": "getNinjaSnapshot",
          "params": {
            "guid": "CAMERA_DEVICE_GUID"
          }
        },
        {
          "handler": "sendToDropbox",
          "params": {
            "guid": "DROPBOX_DEVICE_GUID"
          }
        }
      ],
      "store": {},
      "suspended": false,
      "shortName": "Nerf Gun Shooter",
      "timeout": 0
    }
  ]
}

 

GET rule/:rid

Fetch the specified rule.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/rule/:rid

cURL Example

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

Sample JSON response

{
  "result": 1,
  "error": null,
  "id": 0,
  "data": {
    "rid": 89353,
    "preconditions": [
      {
        "handler": "ninjaChange",
        "params": {
          "guid": "RFID_DEVICE_GUID",
          "to": "10101000101000001010101"
        }
      }
    ],
    "actions": [
      {
        "handler": "ninjaSendCommand",
        "params": {
          "guid": "RELAY_DEVICE_GUID",
          "da": "0"
        }
      },
      {
        "handler": "sleep",
        "params": {
          "guid": "N/A",
          "sleepLength": 3000
        }
      },
      {
        "handler": "ninjaSendCommand",
        "params": {
          "guid": "RELAY_DEVICE_GUID",
          "da": "1"
        }
      },
      {
        "handler": "getNinjaSnapshot",
        "params": {
          "guid": "CAMERA_DEVICE_GUID"
        }
      },
      {
        "handler": "sendToDropbox",
        "params": {
          "guid": "DROPBOX_DEVICE_GUID"
        }
      }
    ],
    "store": {},
    "suspended": false,
    "shortName": "Nerf Gun Shooter",
    "timeout": 0
  }
}

 

PUT rule/:rid

Update a rule.

Parameters
shortName
string
Required
The name of your rule.
Example: "Nerf Gun Shooter"
preconditions
array
Required
Array of precondition handlers. See further documentation.
Example: [{"handler":"ninjaRangeToggle","params":{"guid":"STEALTHYNINJA_2_0_9","between":26,"and":30}}]
actions
array
Required
Array of action handlers. See further documentation.
Example: [{"handler":"sendEmail","params":{"to":"example@example.com","subject":"NINJA","body":"Hello World!","guid":"EMAIL_GUID"}}]
timeout
number
Optional
Number of seconds to wait before executing this rule again.
Example: 60

Resource URL

https://api.ninja.is/rest/v0/rule/:rid

cURL Example

Add a timeout of 60 seconds to rule 89353:

curl -X 'PUT' \
     -H 'Content-Type: application/json' \
     -d '{"timeout":60,"shortName":"Nerf Gun Shooter","preconditions":[{"handler":"ninjaChange","params":{"guid":"RFID_DEVICE_GUID","to":"10101000101000001010101"}}],"actions":[{"handler":"ninjaSendCommand","params":{"guid":"RELAY_DEVICE_GUID","da":"0"}},{"handler":"sleep","params":{"guid":"N/A","sleepLength":3000}},{"handler":"ninjaSendCommand","params":{"guid":"RELAY_DEVICE_GUID","da":"1"}},{"handler":"getNinjaSnapshot","params":{"guid":"CAMERA_DEVICE_GUID"}},{"handler":"sendToDropbox","params":{"guid":"DROPBOX_DEVICE_GUID"}}]}' \
     -i https://api.ninja.is/rest/v0/rule/89353?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

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

 

DELETE rule/:rid

Delete a rule.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/rule/:rid

cURL Example

Delete rule 89353:

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

Sample JSON response

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

 

POST rule/:rid/suspend

suspend a rule.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/rule/:rid/suspend

cURL Example

Suspend rule 89353:

curl -X 'POST' \
     -i https://api.ninja.is/rest/v0/rule/89353/suspend?user_access_token=YOUR_ACCESS_TOKEN

Sample JSON response

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

 

DELETE rule/:rid/suspend

Unsuspend a rule.

Parameters
none

Resource URL

https://api.ninja.is/rest/v0/rule/:rid/suspend

cURL Example

Unsuspend rule 89353:

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

Sample JSON response

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