Undagrid API

Devices continually send data to the cloud system. This data is interpreted to an extent and then stored in almost raw form in a database. While processing incoming data, messages are sent to external systems as indicated in the setup of the Undagrid cloud system.

In cloud terms a device is a node. Each node collects data all the time. This data comes from various sources, like the built-in GPS, detection of nodes in the neighbourhood, changes in movement, and many more. Each different type of data is, in cloud terms, a sensor. A sensor can be a physical element in the node, or something the node has found out by other means. Every sensor type has its own data structure in the cloud system.

Data is sent from the nodes to the cloud through gateways. These gateways themselves are also nodes in the cloud. They have a different set of sensors than the nodes representing devices.

The cloud maintains a structure representing the nodes in the system. Each node has a name (also known as its serial or its id) and is identified by a UUID. Each node has sensors. One for each different sort of data collected. Sensors are identified by the node name and the sensor name. Each sensor also has a UUID. The cloud automatically creates the necessary sensors for nodes when messages are received from the gateways.

Every node has an owner. This owner is a user defined in the Undagrid cloud. Users have a name and a password. To access the cloud system via the API this document is about, you must specify the user name and password. You can then access items for which you are authorised.

Nodes, sensors, gateways, everything is a channel in the cloud system. A channel is the entity for which data is recorded. Each node and each sensor has one corresponding channel. When an update is received by the cloud, it uses this relationship to see to which channels the data must be published. Data is at least published for the channel associated with the sensor and the channel for the node.

To facilitate dealing with groups of nodes, a group channel can be created. Nodes and sensors can be linked to group channels and data for all nodes and sensors in a group channel can be accessed via that group. When a sensor is member of a group, updates received for the sensor are published to the channels for the group(s) of which the sensor is a member.

Data in the cloud is stored in time series entries. These entries are linked to channels. Accessing cloud data for the nodes in the system is always done through channels.

The Undagrid API is available to access the items described above.

Currently the API consists of 4 groups of REST services:

groups
nodes
admin
channels

Below, each of these APIs is further described. You can try out the API here. It is a simple playground for accessing the various API call's without having to write any code.

To use the API in your own application, call the REST services described below.

The API is accessed over HTTPS. User id and password must be specified in a standard HTTP basic authentication header.

The responses of the REST services are standard HTTP status codes. Additional to that the services produce response bodies as described further on.

The groups API is used to:

create group channels
add a sensor or node to a group
remove a sensor or node from a group
remove all sensors and nodes from a group
list the sensors and nodes in a group

To create a new group channel issue the REST request described below. The result of the request will be a JSON structure describing the new channel. The current user will automatically have access to the newly created group.

Request

POST to https://api.undagrid.com/v1/groups/{groupName} with an empty body

parameters for the request:

groupName

path

required

string

the name of the new group to create

Response

a JSON object string describing the newly create channel. The following elements are present:

uuid	UUID string	the UUID for the new group, as generated by the system
channelType	string	the type of channel. Always has value "GROUP" with this request
name	string	the name of the channel. This is the group name specified in the request
active	boolean	indicates if this channel is active or not. Always true with this request

An example:

Request - POST

https://api.undagrid.com/v1/groups/NewGroup

Response

{
  "uuid": "85d11960-da45-11e5-8df9-0008ca2993a1",
  "channelType": "GROUP",
  "name": "NewGroup",
  "active": true
}

To add a sensor or node to a group issue the REST request described below.

Request

POST to https://api.undagrid.com/v1/groups/{groupUuid}/{sensorUuid} with empty body

parameters for the request:

groupUuid	path	required	UUID string	the UUID of the group to which to add the sensor or node
sensorUuid	path	required	UUID string	the UUID of the sensor or node to add to the group

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful

An example:

Request - POST

https://api.undagrid.com/v1/groups/85d11960-da45-11e5-8df9-0008ca2993a1/8fff67f0-8def-1234-5678-acde73cc5421

Response

{
  "status": "OK"
}

To remove a sensor or node from a group issue the REST request described below.

Request

DELETE to https://api.undagrid.com/v1/groups/{groupUuid}/{sensorUuid}

parameters for the request:

groupUuid	path	required	UUID string	the UUID of the group from which to remove the sensor or node
sensorUuid	path	required	UUID string	the UUID of the sensor or node to remove from the group

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful

An example:

Request - DELETE

https://api.undagrid.com/v1/groups/85d11960-da45-11e5-8df9-0008ca2993a1/8fff67f0-8def-1234-5678-acde73cc5421

Response

{
  "status": "OK"
}

To remove all sensors and nodes from a group issue the REST request described below.

Request

DELETE to https://api.undagrid.com/v1/groups/{groupUuid}

parameters for the request:

groupUuid

path

required

UUID string

the UUID of the group from which to remove all sensors and nodes

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful

An example:

Request - DELETE

https://api.undagrid.com/v1/groups/85d11960-da45-11e5-8df9-0008ca2993a1

Response

{
  "status": "OK"
}

To list all channels associated with the sensors and nodes in a group issue the REST request described below.

Request

GET to https://api.undagrid.com/v1/groups/{groupUuid}

parameters for the request:

groupUuid

path

required

UUID string

the UUID of the group for which to list all sensors and nodes

Response

a JSON array of objects string with the result of the request. Each item in the array contains the following elements:

uuid	UUID string	the UUID of the channel associated with the seonsor or node
channelType	string	the type of channel. This will be "SENSOR" or "NODE"
name	string	the name of the channel associated with the sensor or node in the group
pushInterval	integer	a field used internally in the Undagrid cloud
active	boolean	indicates if the channel for the sensor or node is activated in the system or not

An example:

Request - GET

https://api.undagrid.com/v1/groups/85d11960-da45-11e5-8df9-0008ca2993a1

Response

[
  {
    "uuid": "84cc5fb0-814c-1145-8111-02d5fecf45f9",
    "channelType": "NODE",
    "name": "SomeNode",
    "pushInterval": 0,
    "active": true
  },
  {
    "uuid": "8fff67f0-8def-1234-5678-acde73cc5421",
    "channelType": "SENSOR",
    "name": "SomeSensor-STAT",
    "pushInterval": 0,
    "active": true
  }
]

Note: the sensor and node UUIDs and names in the response above are made up and are not real data

The nodes API is used to:

commission a node
decommission a node

Data is collected through channels. If a node is defined in the system, it must have a channel to allow data to be stored for it. Sensor channels are created automatically when data is received by the cloud. Nodes, on the other hand, must be commissioned. Commissioning a node node will create a new channel for the node. Also the current user will become the owner of the node, and this user will get access to the newly created channel.

Optionally a group channel can be specified. If that is done, the node is also added to the group. For this to succeed, the current user must have access to the group channel.

To commission a node issue the REST request described below.

Request

POST to https://api.undagrid.com/v1/nodes/{nodeSerial}?name={name}&channelUuid={channelUuid} with empty body

nodeSerial	path	required	string	the serial id of the node to be commissioned
name	query	required	string	the name of the channel that will be created for the node. This name can be different from the node serial
channelUuid	query	optional	UUID string	the UUID of the group channel to which to add the node. If specified this must be a group channel to which you have access. If not specified, the node is not added to a group

Response

a JSON array of objects string with the result of the request. Each item in the array contains the following elements:

uuid	UUID string	the UUID of the newly created channel for the node
channelType	string	the type of channel created. This is "NODE" with this request
name	String	the name of the channel created. This the name you specified in the request
active	boolean	indicates if the channel is activated in the system or not. Always true with this request

An example:

Request - POST

https://api.undagrid.com/v1/nodes/SomeNode2?name=SomeNode2

Response

[
  {
    "uuid": "efabc530-da1a-1234-6543-0008cfabc3a1",
    "channelType": "NODE",
    "name": "SomeNode2",
    "reference": "SomeNode2",
    "active": true
  }
]

Note: the node UUID and name in the response above is made up and are not real data

When a node will not be used any more, it must be decomissioned. Decomissioning a node detaches it from any channels and clears the owning user. The same is done for any sensors for the specified node.

To decomission a node issue the REST request described below.

Request

DELETE to https://api.undagrid.com/nodes/{nodeUuid}

nodeUuid

path

required

UUID string

the UUID of the channel for the node to be decomissioned

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful

An example:

Request - DELETE

https://api.undagrid.com/v1/nodes/efabc530-da1a-1234-6543-0008cfabc3a1

Response

{
  "status": "OK"
}

The admin API is used to check is the Undagrid cloud is operational.

To check if the Undagrid cloud is operational issue the REST request described below

Request

GET to https://api.undagrid.com/admin/ping

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful, indicating that the Undagrid cloud is operational

An example:

Request - GET

https://api.undagrid.com/v1/admin/ping

Response

{
  "status": "OK"
}

The channels API is used to:

set properties for a channel
remove properties from a channel
set the push configuration for a channel
remove the push configuration from the channel
get information for a channel
get data stored for a channel
list all channels accessible to the current user

A channel can have properties. The Undagrid cloud does not use those properties at the moment. If you want to use channel properties, you can add them with this request. Properties are in JSON format. These proberties can be used in simple application to be able to store some extra data on an object, node, group or sensor, and might be used as a curde database.

Please note that setting properties overwrites the old value(s).

To set properties to a channel issue the REST request described below

Request

PUT to https://api.undagrid.com/channels/{channelUuid}/properties?properties={properties}

channelUuid	path	required	UUID string	the UUID of the channel for which to set properties
properties	query	required	@JSON string	a JSON object as a string with the property value(s) to set for this channel. This JSON object overwrites the old property value(s). The string must be properly URI encoded

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful

An example:

Request - GET

https://api.undagrid.com/v1/channels/efabc530-da1a-1234-6543-0008cfabc3a1/properties?properties=%7B%22propValue1%22%3A%20123%2C%20%22propValue2%22%3A%20%22AcG%22%7D

Note: the node UUID in the request above is made up and is not a real UUID. The decoded properties value is: {"propValue1": 123, "propValue2": "AcG"}

Response

{
  "status": "OK"
}

To remove the properties for a channel issue the REST request described below.

Request

DELETE to https://api.undagrid.com/channels/{channelUuid}/properties

channelUuid

path

required

UUID string

the UUID of the channel for which to remove the properties

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful

An example:

Request - DELETE

https://api.undagrid.com/v1/channels/efabc530-da1a-1234-6543-0008cfabc3a1/properties

Note: the node UUID in the request above is made up and is not a real UUID.

Response

{
  "status": "OK"
}

Channel events can be sent to external systems automatically. Events for a channel with pushing set up, are automatically sent to the push URI configured. The configured secret is used to sign the data.

Please note that setting a push configuration overwrites the old values.

To set up pushing for a channel issue the REST request described below.

Pushing of events is currenly only tried once, so if your backend is not alive, you will need to use the history call to access the missing data

Request

PUT to https://api.undagrid.com/channels/{channelUuid}/push

channelUuid	path	required	UUID string	the UUID of the channel for which events are to be pushed
to	query	required	URI	a valid URI to push to. This can be an HTTP or HTTPS endpoint
interval	query	required	integer	the minimum interval in seconds at which push messages are sent. This can be used to limit traffic to your system. The maximum value is 60 seconds. A value of zero means that new messages are pushed immediately.
secret	query	required	string	the secret used to sign messages sent to the push URI. The secret must be at least 8 characters and can contain lower and upper case characters and digits. This secret is then used to sign the POST body data using a SHA256 HMAC. The signature is send in poth a URL parameter as well as a header called "X-Content-HMAC"

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful

An example:

Request - PUT

https://api.undagrid.com/v1/channels/efabc530-da1a-1234-6543-0008cfabc3a1/push?to=https%3A%2F%2Fyourserver.yourcompany.com%2FchannelEvents%2F&interval=28&secret=A9hj5FGc92f6

Note: the node UUID in the request above is made up and is not a real UUID. The decoded to value is: https://yourserver.yourcompany.com/channelEvents/

Response

{
  "status": "OK"
}

To remove the push configuration for a channel issue the REST request described below.

Request

DELETE to https://api.undagrid.com/channels/{channelUuid}/push

channelUuid

path

required

UUID string

the UUID of the channel for which to remove push configuration

Response

a JSON object string with the result of the request. The following element is present:

status

string

the result of the request. Status is "OK" if the request was successful

An example:

Request - DELETE

https://api.undagrid.com/v1/channels/efabc530-da1a-1234-6543-0008cfabc3a1/push

Note: the node UUID in the request above is made up and is not a real UUID.

Response

{
  "status": "OK"
}

To get information about a channel issue the REST request described below.

Please note that the configured secret is never returned.

Request

GET to https://api.undagrid.com/channels/{channelUuid}

channelUuid

path

required

UUID string

the UUID of the channel for which to retrieve information

Response

a JSON object string with the result of the request. The following elements are present:

uuid	string	the UUID of the channel for which the information is returned
channelType	string	the type of the channel
pushUrl	URI string	the configured push URI
pushInterval	integer	the configured push interval
active	boolean	indicates if the channel is activated or not
properties	JSON object	the configured properties. This item is not returned if no properties are set for the channel

An example:

Request - GET

https://api.undagrid.com/v1/channels/efabc530-da1a-1234-6543-0008cfabc3a1

Note: the node UUID in the request above is made up and is not a real UUID.

Response

{
  "uuid": "efabc530-da1a-1234-6543-0008cfabc3a1",
  "channelType": "GROUP",
  "name": "SomeGroup",
  "pushURL": "https://yourserver.yourcompany.com/channelEvents/",
  "pushInterval": 28,
  "active": true,
  "properties": {
    "propValue1": 123,
    "propValue2": "AcG"
  }
}

Note: the data in the response above is made up and is not real data.

Data is accessible for channels. A sensor channel is used to access data for a single sensor. A node channel to access data for a node and all its sensors and a group channel for all nodes wit their sensors that are members of the group.

The history API is used to access the data. Data can be retrieved for at most one day or at most 10.000 items at a time.

Data is returned in what we call timeslices. Each timeslice has some standard information and some data in a structure specific for the sensor type.

To access data stored in the Undagrid cloud issue the REST request described below

Request

GET to https://api.undagrid.com/channels/{channelUuid}/history?from={from}&to={to}&count={count}

channelUuid	path	required	UUID string	the UUID of the channel for which to access data
from	query	optional	long	the start date-time for which to retrieve data. This field is specified in epoch time in seconds or milliseconds
to	query	optional	long	the end date-time for which to retrieve data. This field is specified in epoch time in seconds or milliseconds. If from is specified, to must also be specified. To must be after from and must not be greater than 1 day later than from
count	query	optional	integer	the maximum number of items to retrieve. The highest value that can be specified is 10.000. If from and to are specified and count is not specified, all items for the specified period will be returned, also if there are more than 10.000. If from, to, and count are all not specified, the last timselice for the channel is returned

Response

a JSON array of objects string with the results of the request is returned. Each item in the array contains the following elements

channelUuid	UUID string	the UUID of the channel for which the timeslice is available
channelName	String	the name of the channel
gatewayUuid	UUID string	the UUID of the gateway through which this data is received
nodeUuid	UUID string	the UUID of the channel for the node for which this timeslice contains data
nodeName	string	the name of the channel for the node for which this timselice contains data
sensorUuid	UUID string	the UUID of the sensor for which this is a timeslive
sensorName	string	the name of the channel for the sensor for which this timeslice contains the data
ts	long	timestamp in epoch milliseconds for this timeslice. This is the time the gateway sent the data to the backend
type	string	the sensor type for the data in this timeslice. The type is the name of the value type as described below
value	JSON object string	the data specific to the sensor type for this timeslice. Each different sensor type has a different set of values it sends to the cloud. This element contains these values in a JSON object string. The value types are described below

The various value types are described below. The elements described are all optionally available. This means that not all elements are necessarily available in each timeslice with the type.

Value type CONN

function	integer	the function code of the node - this indicates the application(s) that run on the node
version	integer	the version of the software running on the node

Value type GPS

ts	long	node timestamp in epoch seconds for the GPS message
hdop	double	horizontal dilution of precision of the GPS measurement. A value of 1.0 means an accuraccy of about a 5 meters radius.
fix	integer	GPS fix
view	long	GPS view
stationary	boolean	true if the node is stationary, false if not. In the last case, there will be no GPS information available in the message
lat	double	lattitude	lattitude
lon	double	longitude
calculated	boolean	indicates if this location information was calculated in the cloud by other means than GPS

Value type TEMP

ts	long	time the measurement was taken
temperature	integer	the temperature in degrees Celsius (centigrade)

An example:

Request - GET

https://api.undagrid.com/v1/channels/4ae91234-3333-1111-bbbb-fe1239886543/history?count=3

Note: the node UUID request above is made up and is not a real UUID.

Response

[
  {
    "channelUuid": "4ae91234-3333-1111-bbbb-fe1239886543",
    "channelName": "SomeGroup",
    "gatewayUuid": "4f6b1234-3333-1111-8888-02c2e9865437",
    "gatewayName": "SomeGateway",
    "nodeUuid": "72a71234-3333-1111-bbbb-02c2e4321447",
    "nodeName": "SomeNode",
    "sensorUuid": "72d55555-3333-1111-bbbb-02c43218c447",
    "sensorName": "sensor_ABCDEF-G",
    "ts": 1415704825000,
    "type": "GPS",
    "value": {
      "ts": 1415704825,
      "lat": 54.310553,
      "lon": 3.7595175,
      "hdop": 1.4,
      "fix": 1,
      "view": 6,
      "stationary": true
    }
  },
  {
    "channelUuid": "4ae91234-3333-1111-bbbb-fe1239886543",
    "channelName": "SomeGroup",
    "gatewayUuid": "4f6b1234-3333-1111-8888-02c2e9865437",
    "gatewayName": "SomeGateway",
    "nodeUuid": "72a77777-3333-1111-bbbb-02c2e9432147",
    "nodeName": "AnotherNode",
    "sensorUuid": "72ddddd0-3333-1111-bbbb-02c2e9843217",
    "sensorName": "sensor_CDEFH-G",
    "ts": 1415704865000,
    "type": "GPS",
    "value": {
      "stationary": false
    }
  }
  }
]

Note: the data in the response above is made up and not real.

To list all channels accessible to the current user issue the REST request below

Request

GET to https://api.undagrid.com/channels?channelType={channelType}&filter={filter}

channelType	query	optional	string	if specified, only channels of that tpe are listede. If not specified all channels for the user are returned. Possible values are "GROUP", "NODE", or "SENSOR"
filter	query	optional	string	if specified this limits the channels returned to those where the specified string occurs in the name of the channel

Response

a JSON array of objects string with the results of the request is returned. Each item in the array contains the following elements

uuid	string	the UUID of the channel for which the information is returned
channelType	string	the type of the channel
pushUrl	URI string	the configured push URI
pushInterval	integer	the configured push interval
active	boolean	indicates if the channel is activated or not
properties	JSON object	the configured properties. This item is not returned if no properties are set for the channel

An example:

Request - GET

https://api.undagrid.com/v1/channels/?filter=Some

Response

[
            {
  "uuid": "efabbbbb-da1a-1234-6543-0008cfabc3a1",
  "channelType": "GROUP",
  "name": "SomeGroup",
  "pushURL": "https://yourserver.yourcompany.com/channelEvents/",
  "pushInterval": 28,
  "active": true,
  "properties": {
    "propValue1": 123,
    "propValue2": "AcG"
  },
  {
  "uuid": "efabcccc-dddd-1234-6543-0008cfabc3a1",
  "channelType": "NODE",
  "name": "SomeNode",
  "pushURL": "https://yourserver.yourcompany.com/channelEvents/",
  "pushInterval": 28,
  "active": true,
  "properties": {
    "propValue1": 123,
    "propValue2": "AcGN"
  },
  }
  "uuid": "efabc530-aaaa-1234-6543-5558cfabc3a1",
  "channelType": "SENSOR",
  "name": "sensor_ABCDEF-G",
  "pushURL": "https://yourserver.yourcompany.com/channelEvents/",
  "pushInterval": 28,
  "active": true,
  "properties": {
    "propValue1": 123,
    "propValue2": "AcGS"
  ]
}

Note: the data in the response above is made up and is not real data.

Undagrid API

Introduction

Groups API

Create a group channel

Add a sensor or node to a group

Remove a sensor or node from a group

Remove all sensors and nodes from a group

List all sensors and nodes in a group

Nodes API

Commision a node

Decommission a node

Admin API

Ping the Undagrid cloud

Channels API

Set properties for a channel

Remove properties from a channel

Set the push configuration for a channel

Remove the push configuration from a channel

Get information for a channel

Get data stored for a channel

List all channels accessible to the current user

Copyright