API

An Application Programming Interface (API) is the means by which one system may interact with another system and is essentially a machine to machine system interface. The Ardtweeno system exposes this HTTP REST API which can be operated by any device capable of creating HTTP connections to the gateway for this reason. The HTTP REST API is the main interface for working with the Ardtweeno Application Gateway, it allows third parties to develop custom front-ends or data-aggregation systems which interact with the gateway, the REST API allows multiple SerialParser instances to communicate with the gateway from multiple remote locations as the method for adding new data to the gateway is also only possibly by communicating to the Ardtweeno Gateway through the HTTP REST API.

HTTP REST Interface

The following HTTP REST API Version 1 set for release with the ER2 product and contains the following features:

Data Manipulation

• Add/List packets in the Ardtweeno system

• List Node data

• List Zone data

• Add Node to the Watchlist

System Administration

• List system configuration settings

• Start/Stop the SerialRouter subsystem

• Restart the gateway host

• Retrieve current and historical load data for the gateway

Table 1. API Methods Table and Definitions

URL	Method	Function
/api/v1/nodes	GET	Retrieve a list of Nodes. Returns JSON string
/api/v1/packets	GET	Retrieve a list of Packets. Returns JSON string
/api/v1/packets	POST	Add a packet to the Ardtweeno system
/api/v1/watch/node	POST	Add a node to a watch list, and instruct the gateway to update watcher with push notifications
/api/v1/watch/node	GET	Check if a node is being watched {"watched":true|false}
/api/v1/watch	GET	Returns Array of Hash {"node":String, "notifyURL":String, "method":String, "timeout":String}
/api/v1/zones	GET	Retrieve information on zones
/api/v1/zones/testzone0	GET	Retrieve information on zone testzone0
/api/v1/system/start	GET	Starts the localhost Ardtweeno SerialRouter
/api/v1/system/stop	GET	Stops the localhost Ardtweeno SerialRouter
/api/v1/system/reboot	GET	Reboots the gateway host
/api/v1/system/config	GET	Read the system configuration file contents
/api/v1/system/status	GET	Read the current system status
/api/v1/system/status/list	GET	Retrieve the last 15 minutes worth of system status data
/b97cb9ae44747ee263363463b7e56/create/post	GET	Access the front page news post form
/b97cb9ae44747ee263363463b7e56/create/post	POST	Add a post to the front end

HTTP REST API Authentication

All API requests currently require authentication by means of an API key. This key is configured in the /home/user/.ardtweeno/conf.yaml configuration file. This API key must be accompanied with any API calls to the REST API otherwise they will be ignored entirely and return a HTTP 404 response.

Table 2. API Key Authentication

key

/api/v1/packets?key=0dfdFFeeDx

Return all packets and authenticate with the API key 0dfdFFeeDx

The following pagination options are available for manipulating the data returned by the API

Table 3. REST API Pagination

Parameter	Sample Usage	Function
offset	/api/v1/packets?offset=50	Returns packets excluding the first 50
length	/api/v1/packets?length=50	Return the first 50 packets only
sort	/api/v1/packets?sort=(desc or asc)	Return all packets in decending order, defaults to ascending order

Posting Packet

The Packet is the representation of a single piece of information transmitted on the Mesh Network by one of the managed nodes. The packet itself can contain data from one or all sensors attached to an individual node on the mesh network. The HTTP REST API expects data in a specific format otherwise it will be rejected as malformed data. The following JSON objects show the format expected by the HTTP REST API /packets interface when posting a new data packet to the system as a HTTP POST request.

Target and HTTP Method Expected

POST /api/v1/packets HTTP/1.1

Parameters Expected

payload key

Payload

The payload parameter must contain JSON data in the format specified below:

Field	Type	Description
key	string	The authentication key for this node
data	array	Array of data values, order is important, should match the sensors defined in the sensorlist field inside the corresponding node

The following is a sample packet in JSON form suitable for the payload parameter.

{
  "data": [
    25.5,
    999,
    10.2
  ],
  "key": "authenticationkeyfornode"
}

Key

The key parameter must contain the API authentication key.

NOTE: The API key is different to the node authentication key. One is for gaining access to the REST API, the other is for giving an NODE access to the mesh network

The following is a full example demonstrating how one might work with the API in order to add a Packet to the Ardtweeno Gateway. This is Ruby code and requires the typhoeus gem to be installed and available for use.

require 'rubygems'
require 'typhoeus'


packet = '{"data":[25.5, 999, 10.2], "key":"abcXYZ123etc"}'
apikey = 'abc33fssfe'


Typhoeus::Request.post("http://ardtweeno-hostname/packets",
:body => {:payload => packet, :key => apikey})

Retrieving Packets

The Processed Packet contains extra meta data required by the Ardtweeno Application Gateway for each Packet recieved or transmitted on the Mesh Network. Calls to the API to retrieve Packets from the DB using the list interface return JSON as shown below.

Target

GET /api/v1/packets

Parameters Expected

key

Sample Usage

/api/v1/packets?length=2&key=APIkey

{"packets":[{
  "date": "2012-11-07",
  "hour": 9,
  "minute": 36,
  "node": "node0",
  "key": "0123456789abcdef",
  "seqNo": 0,
  "data": [
    23.5,
    997.8,
    30
  ]
},
{
  "date": "2012-11-07",
  "hour": 9,
  "minute": 37,
  "node": "node0",
  "key": "0123456789abcdef",
  "seqNo": 1,
  "data": [
    25.5,
    994.8,
    30
  ]
}],"total":200,"found":2}

Retrieving Nodes

The Ardtweeno::Node is the representation of all the information required to manage a physical node on the mesh network. The API offers the means to query the Ardtweeno Application Gateway and retrieve the list of information stored on each node. See below for an example how to interact with the gateway, and the reponse being generated by the gateway. With v1 of the Ardtweeno API specification, the nodes target is read only.

Target

GET /api/v1/nodes

Parameters Expected

key

Sample Usage

/api/v1/nodes?key=APIkey

{"nodes":[{
  "name": "node0",
  "key": "500d81aafe637717a52f8650e54206e64da33d27",
  "description": "This node is outside",
  "version": "0.1.0",
  "sensors": [
    "Temperature",
    "Barometric Pressure",
    "Altitude"
  ]
},
{
  "name": "node1",
  "key": "f937c37e949d9efa20d2958af309235c73ec039a",
  "description": "This node is inside",
  "version": "0.1.0",
  "sensors": [
    "Temperature",
    "Barometric Pressure",
    "Altitude"
  ]
}],"total":2,"found":2}

Adding a Node to the Watchlist

The Ardtweeno Application Gateway allows individual nodes to be placed on a watchlist, with the instruction of sending a push notification to the watcher when this node receives packets. This system could potentially be used as an alarm and offers the ability to check the data received from this particular node immediately rather than constantly polling the gateway looking for updates to a particular node.

Target

POST /api/v1/watch/:node

Parameters Expected

key, node, notifyURL, method, timeout

Sample Usage

See the following example to see a node being placed on the watchlist. In this example the Ardtweeno Gateway is running on localhost. The notifyURL parameter is the URL which you wish the Ardtweeno Gateway to notify with a push notification.

require 'rubygems'
require 'typhoeus'
require 'json'


body = {:key=> "1230aea77d7bd38898fec74a75a87738dea9f657",
                :notifyURL=>"http://some-server/push/notifications",
                :method=>"POST",
                :timeout=>"60"}

puts Typhoeus::Request.post("http://localhost:4567/api/v1/watch/node2", :body=>body)

When the gateway sends a push notification it is in JSON format and looks like the following, this push notification system is pre-alpha quality and was rushed in to meet the project deadline. This can be greatly improved in future development.

{
  "title":"Push notification",
  "content":"node2",
  "code":""
}

Retrieving Zones

The Ardtweeno::Node can be grouped into zones by the Ardtweeno Gateway. Zones are a means to assign separate API keys to authenticate and partition groups of nodes from one another. The API offers the means to query the gateway using the HTTP REST API to retrieve information on the nodes and the particular zone they are associated with.

Target

GET /api/v1/zones GET /api/v1/zones/:zonename

Parameters Expected

key

Sample Usage

/api/v1/zones?zonename=testzone0&key=APIkey /api/v1/zones/testzone0?key=APIkey

{
  "zones": [
    {
      "zonename": "testzone0",
      "key": "455a807bb34b1976bac820b07c263ee81bd267cc",
      "nodes": [
        "node0",
        "node1"
      ]
    }
  ],
  "total": 2,
  "found": 1
}

Ardtweeno API Front End

The following image shows the Ardtweeno HTTP Interface which is powered by the Sinatra micro web application framework. Users who connect directly to the gateway are greeted with this screen.

The ER2 version of Ardtweeno contains URI links to where the source for the system is contained on github.com along with a URI link to my personal blog. A simple status indicator is shown on this page also which shows whether or not the local SerialParser instance is running.

Content for this page can be either added manually using the form available at the http://<ardtweeno-server-address>/<newsURI>/create/post. The newsURI parameter is loaded from the ~/.ardtweeno/conf.yaml file. These front end posts can also be created by creating a HTTP POST request in the following way:

Target

POST /<newsURI>/create/post

Parameters Expected

title String containing the post title content String containing the post content code String containing code snippets, or preformatted output

Sample Usage

See the following for an example

require 'rubygems'
require 'typhoeus'


title = 'Hi This is a Title'
content = 'This is some content lorum ipsum, blah blah etc..'
code = 'require "json"; puts JSON.pretty_generate(
  JSON.parse("{'brownfox':'Jumped over the lazy dog'}".to_json)
  );'


Typhoeus::Request.post("http://ardtweeno-hostname/packets",
:body => {:title=>title, :content=>content, :code=>code})

The output is something similar to the post seen in the image below: