RESTful cloud API methods¶

Environment variables¶

Variable	Description
url	https://broker.ubiworx.com/api URL to use for all queries.
gateway_id	The ID of one of the gateways in your account.
config_name	The configuration name that a user has provide when the configuration was created.
sensor_id	The ID of a sensor or actuator that belongs to one gateway.
alarm_uid	The unique identifier of an alarm type.

Gateways¶

Get gateway details¶

GET {{url}}/gateways/{{gateway_id}}

Request details for one or all gateways belonging to a vendor.

Example all: https://broker.ubiworx.com/api/gateways

Example one: https://broker.ubiworx.com/api/gateways/2345

Create new gateway¶

POST {{url}}/gateways/create

Create a new gateway by sending a JSON object.

NOTE: Once the gateway has been created its **gateway_id* can NOT be changed.*

Example: https://broker.ubiworx.com/api/gateways/create

Example of JSON body to POST when creating a new gateway.

{
  "gateway_id": "Lab1",
  "gateway_name": "My Lab 1",
  "MAC": "10:30:20:40:50",
  "mobile": 0,
  "latitude": 52.555,
  "longitude": -8.388,
  "keepalive_interval": 400
}

Update gateway details¶

POST {{url}}/gateways/update

Update gateway details by sending a JSON object.

NOTE: *gateway_id is required, folowed by any of the fields to update.*

Example: https://broker.ubiworx.com/api/gateways/update

Example of JSON body to POST when updating a gateway:

{
 "gateway_id": "Lab1",
 "gateway_name": "My Lab 1"
}

Gateways configuration¶

Get configuration for a gateway¶

GET {{url}}/gateways/{{gateway_id}}/configuration/{{config_name}}

Get one or all the configuration information for one gateway.

Example all: https://broker.ubiworx.com/api/gateways/2345/configuration

Example one: https://broker.ubiworx.com/api/gateways/2345/configuration/ESSID

Create new gateway configuration¶

POST {{url}}/gateways/{{gateway_id}}/configuration/create

Create new gateway configuration by sending a JSON object

NOTE: *config_name are defined by users and can represent any configuration value that the user wants to store (ESSID, password, ...)*

Example: http://broker.ubiworx.com/api/gateways/2345/configuration/create

{
  "ESSID": "MySSID1",
  "ESSID_Pass": "random-pass!2342!",
  "Node_Type": "CL"
}

Update gateway configuration¶

POST {{url}}/gateways/{{gateway_id}}/configuration/update

Update one or multiple gateway configuration values by sending a JSON object.

Example: https://broker.ubiworx.com/api/gateways/2345/configuration/update

{
  "Node_Type": "CL",
  "ESSID": "CL",
  .
  .
  .
  "MyValue": "user defined"
}

Sync gateway changes.¶

Trigger sync¶

GET {{url}}/gateways/{{gateway_id}}/update

Trigger a gateway to re-annonce and force a sync of the latest changes down to the gateway. If the gateway is not currently connected the sync will hapen as soon as the gateway connects.

NOTE: This will trigger the gateway to update its configuration and list of sensors.

Example: https://broker.ubiworx.com/api/gateways/2345/update

Sensors¶

Get sensors¶

GET {{url}}/gateways/{{gateway_id}}/sensors/{{sensor_id}}

Get details for one or all sensors/actuators that belong to a gateway.

Example all: https://broker.ubiworx.com/api/gateways/2345/sensors/

Example one: https://broker.ubiworx.com/api/gateways/2345/sensors/freeCPU

Create new sensor¶

POST {{url}}/gateways/{{gateway_id}}/sensors/create

Create a new sensor or actuator by sending a JSON object.

NOTE: Once the sensor/actuator has been created its **sensor_id* can NOT be changed.*

Example of JSON body to POST:

{
  "sensor_id":  "bedroomTemp2",
  "sensor_name":  "Bedroom Temp 2",
  "sensor_type":  0,
  "hw_addr":      "none",
  "scale":        1,
  "offset":       0,
  "max":          120,
  "min":          -30,
  "units":        "degrees",
  "mobile":       0,
  "latitude":     52.8778,
  "longitude":    -8.4526
}

Update sensor¶

POST {{url}}/gateways/{{gateway_id}}/sensors/update

Update a sensor or actuator by sending a JSON object.

NOTE: *sensor_id is required, folowed by any of the fields to update.*

Example of JSON body to POST:

{
    "sensor_id":    "bedroomTemp2",
    "latitude":     52.8778,
    "longitude":    -8.4526
}

Historical sensor data¶

Available parameters:

last=x - get the last sample
- Example: last=1
startDate ( UNIX time - seconds since 00:00:00 1/1/1970 (in UTC) )
- Example: startDate=1408711173
endDate ( UNIX time - seconds since 00:00:00 1/1/1970 (in UTC) )
- Example: endDate=1508711173
method - currently available method are: none, avg, min and max
- Example: method=avg
max - maximum number of samples to return
- Example: max=100

Get RANGE limited data¶

GET {{url}}/gateways/{{gateway_id}}/sensors/{{sensor_id}} /data?startDate=1408711173&endDate=1508711173

Range limited data for one sensor.

This request returns a JSON object that contains only samples between the startData and endDate time interval. Time interval is based on UNIX time - seconds since 00:00:00 1/1/1970 (in UTC).

Example: https://broker.ubiworx.com/api/gateways/gateway_foo/sensors/cpu1/data?startDate=1&endDate=1455189157

Example of JSON body response from a GET data request.

{
    "status": "ok",
    "message": "success",
    "date": "2016-02-08 21:40:07",
    "vendor_name": "your_vendor_name",
    "vendor_ID": "your_vendor_id",
    "gateway_id": "gateway_foo",
    "sensor_id": "cpu1",
    "response": [
        {
            "val": "95.12",
            "sec": 1454000010,
            "usec": 473892,
            "lat": 52.6718548,
            "long": -8.5492271
        },
        {
            "val": "95.20",
            "sec": 1454000020,
            "usec": 194384,
            "lat": 52.6718548,
            "long": -8.5492271
        }
    ]
}

Get LAST sample¶

GET {{url}}/gateways/{{gateway_id}}/sensors/{{sensor_id}}/data?last=1

This request returns a JSON object with only the last recorded sample for a sensor.

Get samples using MAXIMUM and METHOD¶

GET {{url}}/gateways/{{gateway_id}}/sensors/{{sensor_id}} /data?**max=100**&method=avg&startDate=1408711173&endDate=1508711173

The max parameter can be used to limit the amount of samples the query returns. The JSON response will contain at least “max” samples.

The “max” value is used to calculate a step in the form of “samples in range” / “max” (rounded down to integer). Steps can be also seen as groups of samples. The values of the samples within those groups can be modified by using the “method” parameter. The available methods are none, min, max and avg. Using “method” by itself makes no effect. It only makes sense when “max” is used.

Example: using the range “startDate=1408711173&endDate=1408712141” the API returns 1000 samples. If max=123 is specified, the step will be 8 and the query will now return 125 samples. If method=avg is also specified, samples will be averaged in groups of 8.

Get and Set live data¶

Get live data¶

GET {{url}}/gateways/{{gateway_id}}/sensors/{{sensor_id}}/commands

Request the current value for one sensor or actuator from a gateway.

NOTE: This request will retrieve a value from the gateway in real time. The result is the latest reading for that sensor on that gateway If connecting to the gateway takes longer tha 5 seconds the request will be cancelled.

Example: https://broker.ubiworx.com/api/gateways/gateway_foo/sensors/cpu1/commands

Post data to the gateway¶

POST {{url}}/gateways/{{gateway_id}}/sensors/{{sensor_id}}/commands

SET the current value of one sensor or actuator by sending a JSON object

NOTE: This request will **set* the value localy on the gateway in real time.* The resonse is the lastest reading for that sensor on that gateway and can be used to validate that the set command was successfull. If connecting to the gateway takes longer tha 5 seconds the request will be cancelled.

Example: https://broker.ubiworx.com/api/gateways/gateway_foo/sensors/LED/commands

Example of JSON body to POST when setting a value for a sensor:

{
    "set": 1
}

Alarms¶

Get alarms¶

GET {{url}}/alarms/{{alarm_uid}}

Get details of all the alarms belonging to a vendor.

NOTE: Specify the **alarm_uid* to retrieve information for just one alarm. To see events generated by an alarm pease see the **Alarm Events* section of the documentation.*

Create alarms¶

POST {{url}}/alarms/created

Tell the broker what alarms to expect from the gateway.

NOTE: Users can create **one* or multiple alarms at the same time inside one request.*

Example of expected JSON:

[{
    'id': '12345',
    'did': 'gateway_id',
    'sid': 'sensor_id',
    'cat': 'temperature',
    'name': 'max temperature exceeded'
},
.
.
.
{
    'id': '5678',
    'did': 'gateway_id',
    'sid': 'sensor_id',
    'cat': 'temperature',
    'name': 'min temperature reached'
}]

Set actions for alarms¶

POST {{url}}/alarms/set_actions

Set actions to be done when the different alarms are triggered.

Note: Only supports email notifications Users can set actions for **one* or multiple alarms at the same time inside one request.*

Example of expected JSON:

[{
    'auid': '12345',
    'acts': ['email']
},
{
    'auid': '5678',
    'acts': ['email']
},
.
.
.
{
    'auid': '43434',
    'acts': ['email']
}]

Delete alarms¶

POST {{url}}/alarms/delete

Delete one or multiple alarms inside one request.

Example of expected JSON:

[
{ 'uid': '12345' },
{ 'uid': '55783' },
.
.
.
{ 'uid': '43456' }
]

Alarm events¶

Get events for one alarm¶

GET {{url}}/alarms/{{alarm_uid}}/all

Get all events for one alarm.

Example: https://broker.ubiworx.com/api/alarms/2345/all

Acknowledge alarm events¶

POST {{url}}/alarms/acknowledge

Mark one or multiple events as acknowledged inside one request.

Example of expected JSON:

[{
    "seq": 20,
    "ack": 1
},
{
    "seq": 21,
    "ack": 1
},
.
.
.
{
    "seq": 25,
    "ack": 1
}]

Use case¶

The examples are based on JavaScript AJAX requests if the request is sent from other programming languages like Java, Python or Ruby please check the documentation for that language to find the appropriate syntax.

For help on how to formulate a request please see example bellow or visit: http://broker.w3schools.com/ajax/ajax_xmlhttprequest_send.asp

GET a list of gateways (full example)¶

Save the code below in a new file index.html and replace username and password with your details:

<html>
<head></head>
<body>
  <!-- respons will be placed inside this paragraph -->
  <p id="container"></p>


<script type="text/javascript">

(function() {
  function getAllTheGateways() {

    var xmlhttp, encodedString;

    //encode the username and password
    encodedString = btoa('username:password');


    xmlhttp = new XMLHttpRequest();
    xmlhttp.open("GET","https://broker.ubiworx.com/api/gateways",true);

    //set the authentification header
    xmlhttp.setRequestHeader("Authorization", "Basic " + encodedString);

    //handle the response
    xmlhttp.onreadystatechange = function () {
        if (xmlhttp.readyState === 4) {
            if (xmlhttp.status === 200) {
              var container, content;

                //place the respons into the container
                container = document.getElementById('container');
                content = document.createTextNode(xmlhttp.responseText);
                container.appendChild(content);

            }
        }
    };
    //send the request
    xmlhttp.send();
  }

  getAllTheGateways();
})();
</script>
</body>
</html>

The response will be a list of all your gateways in JSON format:

{
  "status":"ok",
  "message":"success",
  "date":"2014-11-07 15:54:16",
  "account_name":"yourVendorName",
  "response":[
    {
      "gateway_id": "00:10:20:40:70:80",
      "gateway_name": "MyHouse",
      "latitude": 51.6659,
      "longitude": -8.98477,
      "mobile": 0,
      "connection_status": 0,
      "last_connection": 1412610198,
      "keepalive_interval": 300
    },
    {
      "gateway_id": "00:30:20:40:70:80",
      "gateway_name": "MyOffice",
      "latitude": 53.6659,
      "longitude": -8.98477,
      "mobile": 0,
      "connection_status": 0,
      "last_connection": 1412610198,
      "keepalive_interval": 300
    },

    .
    .
    .

    {
      "gateway_id": "20:10:20:40:70:80",
      "gateway_name": "MyCar",
      "latitude": 51.9659,
      "longitude": -8.98477,
      "mobile": 1,
      "connection_status": 0,
      "last_connection": 1412610198,
      "keepalive_interval": 300
    }
  ]
}