REST API

Background

The basic structure of the Monesco system is depicted in Figure 1. We work with IoT devices, that are deployed on site – these are interchangeably referred to as gateways or devices. A gateway communicates with sensors or actuators (like relays, pumps and valves) over a wired connection and relays all relevant data to the Monesco Cloud through either a WiFi or cellular connection. All signal processing and interfacing electronics required for interfacing the sensors or actuators are embedded in the gateways.
In Monesco Cloud, all sensors and actuators are collectively referred to as elements. Thus, one gateway/device can provide values for several elements to the Cloud. Furthermore, gateways and elements are grouped into projects in the Cloud. User management and authorization works on the project level.

Users login to the Monesco Cloud web app via https://monesco.consibio.com/, where they have access to real-time visualizations of current state of data, datalogs over time, possibility to setup control rules, alarm systems, real-time analytics and more. Whenever a control rule is defined in the Cloud, it is automatically synced to the relevant gateway, which in turn effectuates the control logic between the appropriate sensor and actuators.

This document describes how data in Monesco Cloud can be retrieved using the Monesco Cloud REST API.

Figure 1: REST API overview

Overview

The base URL of the Monesco Cloud REST API is:

https://monesco.consibio.com/rest

The following REST endpoints are exposed from this base URL:

EndpointTypeParametersDescription
/loginPOSTLogin credentials formatted as plain text:
{
  ”username”: ”<email>”,
  ”password”: ”<pwd>”
}
Used to retrieve the auth token used for all other requests
/list_projectsGETnoneList projects for given user.
/list_gateways_in_projectGET?project_id=<project_id>List gateways for a given project ID.
/list_elements_behind_gatewayGET?gw _id=<gw_id>List elements behind a given gateway ID.
/list_elements_in_projectGET?project_id=<project_id>List all elements in a project with given ID.
/get_element_valueGET?element_id=<element_id>Get the current value of an element with given ID.
/get_datalog_for_elementGET?element_id=<element_id>
?project_id=<project_id>
?from_time=<unix_timestamp>
?to_time=<unix_timestamp>

?interval=<seconds>

Get data from the datalog associated with a given element ID in a project with given ID.

All the GET endpoints uses ID tokens to allow access to the API. This token should be provided in the http header in the format:

Authorization: Bearer {BEARER_TOKEN}

The token is retrieved from the /login endpoint, when correct credentials are provided in the login POST request.

API Endpoints

/login

Type: POST

Parameters

JSON-formatted credentials in plain text:

{
   ”username”: ”<email>”,
   ”password”: ”<pwd>”
}
Return value
{
   ”payload”: {
      token: <ID_token>,
      user_id: <uid>,
      email: <user email>
      expires: <seconds until token expires>     
   },
   ”status”: ”ok”
}

/list_projects

Type: GET

Parameters

None

Return value
{
   ”payload”: {
      ”<project_id>”:
         {”name”: <project.name>},

       ... <additional entries ...
   },
   ”status”: ”ok”
}
Example

Calling

/list_projects

returns:

{
   ”payload”: {
      ”project_id1”: {
         ”name”: ”Project 1”
      },
      ”project_id2”: {
         ”name”: ”Project 2”
      },
   },
   ”status”: ”ok”
}

/list_gateways_in_project

Type: GET

Parameters
<string> project_id
Return value
{
   ”payload”: {
      ”<gw_id>”:
         {”project_id”: <project_id>},

       ... <additional entries ...
   },
   ”status”: ”ok”
}
Example

Calling

/list_gateways_in_project?project_id=project_id1

returns:

{
   ”payload”: {
      ”gw_id1”: {
         ”project_id”: ” project_id1”
      },
      ”gw_id2”: {
         ” project_id”: ” project_id1”
      },
   },
   ”status”: ”ok”
}

/list_elements_behind_gateway

Type: GET

Parameters
<string> gw_id
Return value
{
   ”payload”: {
      ”<element_id>”:
         {
            ”name”: ”<element name>”,
            ”element_type”: “<’monitor’ or ‘actuator’>”,
            ”unit”: ”<unit>”,
            ”type”: ”<type of sensor or actuator>”,
            ”color”: ”<hex color code>”,
            ”description”: ”<Description of the element>”,
            sigDigits: <integer with number of significant digits>
         },

              ... <additional entries ...
   },
   ”status”: ”ok”
}
Example

Calling

/list_elements_behind_gateway?gw_id=gw_id1

returns:

{
   ”payload”: {
      ”element_id1”:
         {
            ”name”: Temp sensor”,
            ”element_type”: “monitor”,
            ”unit”: ”C”,
            ”type”: ”temp”,
            ”color”: ”#950000”,
            ”description”: ”The indoor air temperature”,
            sigDigits: 2
         },
   },
   ”status”: ”ok”
}

/list_elements_in_project

Type: GET

Parameters
<string> project_id
Return value
{
   ”payload”: {
      ”<element_id>”:
         {
            ”name”: ”<element name>”,
            ”element_type”: “<’monitor’ or ‘actuator’>”,
            ”unit”: ”<unit>”,
            ”type”: ”<type of sensor or actuator>”,
            ”color”: ”<hex color code>”,
            ”description”: ”<Description of the element>”,
            sigDigits: <integer with number of significant digits>
         },

              ... <additional entries ...
   },
   ”status”: ”ok”
}
Example

Calling

/list_elements_in_project?project_id=project_id1

returns:

{
   ”payload”: {
      ”element_id1”:
         {
            ”name”: Temp sensor”,
            ”element_type”: “monitor”,
            ”unit”: ”C”,
            ”type”: ”temp”,
            ”color”: ”#950000”,
            ”description”: ”The indoor air temperature”,
            sigDigits: 2
         },
      ”element_id2”:
         {
            ”name”: RH sensor”,
            ”element_type”: “monitor”,
            ”unit”: ”%”,
            ”type”: ”RH”,
            ”color”: ”#5349A8”,
            ”description”: ”The indoor relative humidity”,
            sigDigits: 1
         },
              ... <additional entries ...
   },
   ”status”: ”ok”
}

/get_element_value

Type: GET

Parameters
<string> element_id
Return value
{
   ”payload”: {
      ”val”: <current output value of the element>,
      ”time”: <unix timestamp in seconds when latest value was recorded>
   },
   ”status”: ”ok”
}
Example

Calling

/get_element_value?element_id=element_id1

returns:

{
   ”payload”: {
      ”val”: 22.12,
      ”time”: 1588845438.102
   },
   ”status”: ”ok”
}

/get_datalog_for_element

Type: GET


Description
Get data from the datalog associated with a given element ID in a project with given ID.

Parameters
NameTypeOptional/RequiredDescription
element_id<string>requiredElement ID to retrieve values from.
project_id<string>requiredID of the project, that the element is associated to.
to_time<float>requiredA datalog will be returned with values until this UNIX timestamp (in seconds).
from_time<float>requiredA datalog will be returned with values from this UNIX timestamp (in seconds).
interval<float>optional

Default: 0.0
Desired interval (in seconds) between datapoints. Returns all stored values, if interval=0.0 or if interval is lower than the logging interval set for the element (can be configured in the Monesco Web App). If the interval is larger than the log interval, then a mean of the values in the given interval will be returned.
Return value
{
   ”payload”: [
      {
         ”val”: <Recorded value of element_id at time ”time”>,
         ”time”: <unix timestamp in seconds when the value was recorded>
      },
              ... <additional entries ...
   ],
   ”status”: ”ok”
}
Example

Calling

/get_datalog_for_element?element_id= element_id1&project_id=project_id1 &from_time=1588845438.0&to_time=1588846638.0&interval=3600.0

returns:

{
   ”payload”: [
      {
         ”val”: 22.12,
         ”time”: 1588845438.102
      },
      {
         ”val”: 23.41,
         ”time”: 1588849038.200
      },
      {
         ”val”: 24.97,
         ”time”: 1588852638.904
      },
   ],
   ”status”: ”ok”
}