System-to-System API

S2S gateway has RESTful interface. It will give you a full access to the system:

  • list of units deployed out there
  • list of sensors which are installed on units
  • list of resources which are read by sensors
  • list of measurements (values read from sensors)

All exported datasets are restricted according to export user access rights in a concrete sensors network. You need a valid account in the system for a majority of interface operations.

Supported operations

GET count
reads total number of measurements
GET getStatistics
returns the number of measurements for all available units in a time range
GET findRange
lists requested measurements using our open data schema
GET findRangeSenml
lists requested measurements using SenML data format

For more details see WADL descriptor.

Usage

API supports a direct export of some data values. First, you must obtain a range of export sequence, and then you are able to ask for the respective data. Your remote system should implement this approach as shown in the following examples.

There are two ways:

  • REST/JSON Java API is ideal for your Java-based systems (findRangeSenml is not supported)
  • REST/XML (or JSON) API is ideal for all other systems

REST/JSON Java API

Include our Java module in your pom.xml:

<dependencies>
    ...
    <dependency>
        <groupId>cythres</groupId>
        <artifactId>sensnet-cli</artifactId>
        <version>0.9.5-SNAPSHOT</version>
    </dependency>
    ...
</dependencies>

Now, you can access the interface from your Java code:

try (RestClient client = new RestClient("https://snog.cythres.cz/sn/rest")) {
    LoginSessionNoJpa session = client.login("user@sporilov.cythres.cz", "secret_password", "my application ID");
    // ask for data interval
    Range cnt = client.count(session);

    System.out.println(cnt.toString());

    // retrieve up to 10000 measurements
    ExportBag bag = client.findRange(session, cnt.getMin(), cnt.getMin()+10000);

    print(bag.getUnit());
    print(bag.getSensor());
    print(bag.getResource());
    print(bag.getMeasurement());
}

where

private static <T> void print(Collection<T> collection) {
    for (T a : collection) {
        System.out.println(a.toString());
    }
}

REST/XML

The database entities:

  • data-resource denotes a type of values received from sensors
  • sensor reads values of a single data-resource
  • (measurement) unit includes several sensors

All instances of the entities have unique and constant id. If an entity is removed, a new comer will never get the old one id.

The list of measurements is read by chunks. To specify the chunk boundaries, use the respective ids. Range of the ids is available for your convenience via a method "count".

Export is limited by your user access in the system.

Read the range of measurements

Use https://.../rest/export/count/{login-ticket} to obtain the Range object:

wget --no-check-certificate -qO - https://......

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<range min="71" max="979"/>

or

wget --no-check-certificate --header='Accept: application/json' -qO - https://......

{"min":6456584,"max":15387975}

Read the chunk of measurements

Use https://.../rest/export/{login-ticket}/{from}/{to} to export all measurements with ids between {from} and {to} (including the boundary ids). The export root element is export:

<export>
   <measurement id="71" idUnit="50" idSensor="6" readAt="2013-12-11T13:14:33+01:00" gpsX="15.88184105139226" gpsY="50.35498944018036">44.0</measurement>
   <measurement id="373" idUnit="50" idSensor="6" readAt="2013-12-11T13:17:33+01:00" gpsX="15.88184105139226" gpsY="50.35498944018036">76.0</measurement>
   <measurement id="590" idUnit="50" idSensor="6" readAt="2013-12-11T13:19:33+01:00" gpsX="15.88184105139226" gpsY="50.35498944018036">6.0</measurement>
   <measurement id="721" idUnit="50" idSensor="6" readAt="2013-12-11T13:20:32+01:00" gpsX="15.88184105139226" gpsY="50.35498944018036">36.0</measurement>
   <measurement id="72" idUnit="51" idSensor="6" readAt="2013-12-11T13:14:34+01:00" gpsX="15.5444901436567" gpsY="50.59997214749455">22.0</measurement>
   <measurement id="184" idUnit="51" idSensor="6" readAt="2013-12-11T13:15:33+01:00" gpsX="15.55444901436567" gpsY="50.59997214749455">33.0</measurement>
   <measurement id="206" idUnit="51" idSensor="6" readAt="2013-12-11T13:16:33+01:00" gpsX="15.55444901436567" gpsY="50.59997214749455">65.0</measurement>
   <measurement id="374" idUnit="51" idSensor="6" readAt="2013-12-11T13:17:34+01:00" gpsX="15.55444901436567" gpsY="50.59997214749455">7.0</measurement>
   <measurement id="329" idUnit="52" idSensor="6" readAt="2013-12-11T13:16:34+01:00" gpsX="15.349020851776" gpsY="50.5760624073446">84.0</measurement>
   <measurement id="375" idUnit="52" idSensor="6" readAt="2013-12-11T13:17:35+01:00" gpsX="15.349020851776" gpsY="50.5760624073446">72.0</measurement>
   <measurement id="468" idUnit="52" idSensor="6" readAt="2013-12-11T13:18:34+01:00" gpsX="15.349020851776" gpsY="50.5760624073446">79.0</measurement>
   <measurement id="591" idUnit="53" idSensor="6" readAt="2013-12-11T13:19:35+01:00" gpsX="15.01446340233088" gpsY="50.9200410367921">24.0</measurement>
   <measurement id="864" idUnit="53" idSensor="6" readAt="2013-12-11T13:21:36+01:00" gpsX="15.01446340233088" gpsY="50.9200410367921">10.0</measurement>
   <measurement id="443" idUnit="54" idSensor="6" readAt="2014-02-14T07:09:49+01:00" gpsX="15.11003390792757" gpsY="50.0134738078341">81.0</measurement>
   <measurement id="469" idUnit="54" idSensor="6" readAt="2013-12-11T13:18:36+01:00" gpsX="15.11003390792757" gpsY="50.0134738078341">87.0</measurement>
   <measurement id="978" idUnit="54" idSensor="6" readAt="2013-12-11T13:22:37+01:00" gpsX="15.11003390792757" gpsY="50.0134738078341">58.0</measurement>
   <measurement id="447" idUnit="55" idSensor="6" readAt="2014-02-14T07:09:51+01:00" gpsX="15.85748077183962" gpsY="50.75351597275585">37.0</measurement>
   <measurement id="592" idUnit="55" idSensor="6" readAt="2013-12-11T13:19:37+01:00" gpsX="15.85748077183962" gpsY="50.75351597275585">39.0</measurement>
   <measurement id="73" idUnit="56" idSensor="6" readAt="2013-12-11T13:14:38+01:00" gpsX="15.781905960292" gpsY="50.7426244944334">84.0</measurement>
   <measurement id="330" idUnit="56" idSensor="6" readAt="2013-12-11T13:16:37+01:00" gpsX="15.82781905960292" gpsY="50.74426244944334">27.0</measurement>
   <measurement id="194" idUnit="57" idSensor="6" readAt="2013-12-11T13:15:38+01:00" gpsX="15.52190771978348" gpsY="50.35930190980434">64.0</measurement>
   <measurement id="458" idUnit="57" idSensor="6" readAt="2013-12-11T13:17:39+01:00" gpsX="15.52190771978348" gpsY="50.35930190980434">4.0</measurement>
   <measurement id="470" idUnit="57" idSensor="6" readAt="2013-12-11T13:18:39+01:00" gpsX="15.52190771978348" gpsY="50.35930190980434">59.0</measurement>
   <measurement id="593" idUnit="57" idSensor="6" readAt="2013-12-11T13:19:39+01:00" gpsX="15.52190771978348" gpsY="50.35930190980434">85.0</measurement>
   <measurement id="979" idUnit="57" idSensor="6" readAt="2013-12-11T13:22:39+01:00" gpsX="15.52190771978348" gpsY="50.35930190980434">87.0</measurement>
   <resource idResource="6" units="°C">Teplota uvnitř jednotky</resource>
   <sensor idSensor="6" resource="6">Temperature</sensor>
   <unit idUnit="53" vnet="2" gpsX="15.1446340233088" gpsY="50.9200410367921">pod petkou</unit>
   <unit idUnit="54" vnet="2" gpsX="15.11003390792757" gpsY="50.0134738078341">pod petkou</unit>
   <unit idUnit="55" vnet="2" gpsX="15.85748077183962" gpsY="50.75351597275585">pod petkou</unit>
   <unit idUnit="56" vnet="2" gpsX="15.82781905960292" gpsY="50.74426244944334">pod petkou</unit>
   <unit idUnit="57" vnet="2" gpsX="15.52190771978348" gpsY="50.35930190980434">pod petkou</unit>
   <unit idUnit="50" vnet="2" gpsX="15.88184105139226" gpsY="50.35498944018036">pod petkou</unit>
   <unit idUnit="51" vnet="2" gpsX="15.55444901436567" gpsY="50.59997214749455">pod petkou</unit>
   <unit idUnit="52" vnet="2" gpsX="15.349020851776" gpsY="50.5760624073446">pod petkou</unit>
</export>