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:

.. code:: html


    <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
        }
      ]
    }