Domorela's Blog: Virtual Lab with Domorela DMRL1: Testing with REST API: Introduction

The best way to take advantage of the power of Domorela is via their IoT capabilities, this is achieved using its REST API. Thanks to Domorela's REST API is possible to communicate with a Domorela unit from other systems in order to:

1. obtain values to make statistical analysis, allowing to optimize energy savings and achieve predictive maintenance
2. send commands to the elements of the installation, extending their capabilities beyond the limits of the WUI views and controls 

We will test same things as we do with the WUI, but we will do it sending queries to the KNX service of the API. To perform queries we will use scripts based in a well known Open Source tool called cURL. This tool can be compiled for your system from source code and also there are downloadable binaries for different CPU architectures and many Operating Sytems: GNU/Linux, FreeBSD, UNIX based as AIX, HPUX, Solaris and others, and also Win32 and Win64 executables.  

To send queries to Domorela's REST API first we need to obtain a token sending user credentials as parameters of a query to the AAA service, as we are using HTTPS the data will be sent encrypted and no worries at all (but keep your scripts including these commands in a protected folder of your system):

$ curl -c .cookies "https://hostname:8083/admin/api/token?user=XXXX&passwd=XXXX" > /dev/null; were .cookies is a the name of the file that will store token as a cookie

As you can read in the above command, we are storing cookies in a hidden file by using option -c of cURL command. The name of this hidden file will be used in the rest of queries as parameter of the option -b, in order to pass the obtained token for validation purposes without the need to send again user credentials.

For example, we can execute internal commands of Domorela, intended to communicate with KNX BUS, by sending a query in the next form to the KNX service and store the result in an XML file:

$ curl -b .cookies --data-binary "${@data}" "https://$host:8083/admin/api/knx?ref=knxcmd/" > result.xml

Were data is the name of a file containing the POST data in the form of an Str oBIX object encoded in XML which value (val) are command values encoded in Base64, in this example we use base64 command from GNU core utils to encode commands:

$ echo "<str name='comandos' val='`base64 cmdFile`'/>" > data; were cmdFile is the name of the file containing commands

So, one of the ways to communicate with Domorela's REST API is writing system custom scripts using cURL commands that could be called from any application capable to call system scripts.

The other way is by sending HTTP requests from any application or platform capable to communicate with remote systems using HTTPS protocol.

In our next article we will test Lighting and HVAC in the Virtual Lab using the REST API.