1. Table of Contents

• 1. Table of Contents

• 2. Wording

• 3. Communication Concept elproCLOUD <> external Application

  • REST-API for requesting data

• 4. Version of the REST-API

• 5. General for all Requests

  • 5.1 Security Scheme Type

  • 5.2 User Scope

  • 5.3 Http Error Codes

  • 5.4 Request and Response Schema

• 6 Devices

• 7 Sensors

• 8 Public Endpoints and Technical Specification

2. Wording

Physical device

A physical device is identified by a serial number and has 1 to n channels.
Each channel can be configured independently (e.g. own measurement interval) and has one or more sensors, which can provide 1 to m different sensor values.
For example;

• one value: temperature (for a Temperature-Sensor)

• two-tuples of: relative humidity and temperature (for a rH-sensor)

• three-tuples of: status, #changes, relative on (for a DI-sensor)

Virtual representation with alarming

In elproCLOUD we have a one to one mapping of device and channel.
For the values of a sensor we have an one to n mapping to virtual sensors.

A virtual sensor is created for every configuration of a real sensor and is used to attach different type of alarms to the same sensor value.

3. Communication Concept elproCLOUD <> external Application

REST-API for requesting data

The communication between the elproCLOUD and the external application is realized via a REST-API 1<=2 and 4=>3. The interface 1<=2 is used to request information by external application from the elproCLOUD. The interface 4=>3 will provide information that was requested by the external application.

The communication runs typically in the following sequence:

The device will send its data and occurences in defined fix intevall to the elproCLOUD.
There are mechanismens, where the device will send its data directly to the elproCLOUD and will not wait for the next communication interval.

The customer app requests the data from elproCLOUD via the REST-API on demand or in a self defined intervall. This interval should be defined based on a risk-assesment.

4. Version of the REST-API

For the REST-API a versioning mechanism is implemented.

The versioning includes a Major and a Minor number.

Major numbers will provide an interface to the elproCLOUD and will be increased, if the functionality of the interface is dramatically changed. Minor numbers will be increased, if information is added to the returned data structure. 

Major REST-API Versions will be still available via the URL.

• elprocloud_request_url/api/v1/…    (for v1 of the REST-API)

• elprocloud_request_url/api/v2/…    (for v2 of the REST-API)

 Major.Minor Versioning will be included in the returned json response.

{

"version": "<Major.Minor>",

}

5. General for all Requests

5.1 Security Scheme Type

Initially, ELPRO sets up an API key for a dedicated user of an organization.

Provide your API authorization code in the Request Header as Key and Value: 

In case of lack or mismatch, an Error message with HTTP Status 401 “Unauthorized” will be returned.

5.2 User Scope

Retrieved data is in the scope of the organization of the authenticated API User. It will be returned with HTTP-Statuscode 200 (Success).

5.3 Http Error Codes

5.4 Request and Response Schema

Note that any JSON accepted and returned by the API must follow the JSON standard as defined in the ECMA-404 standard with the following amendments.

1. JSON property names are case invariant and no guarantee can be made regarding the casing of names, which are returned by the API. This means that no difference is made between uppercase and lowercase letters in property names.

2. The relative order of JSON names in responses is not be guaranteed. This means that the order of properties in the responses should not be depended on, when parsing and processing responses.

6 Devices

Representation of devices are identified by their unique serial numbers. These data objects carry a subset of information, as well as a list of SensorIds for data sinks, which contain measurement data. With the given API key, the user and the linked devices are identified.

7 Sensors

Sensors represent a data sink holding the data of a run. Each sensor has a start and end date. Its sensor id is unique and links to measurements, geolocation and occurrence data.

Once the Device is restarted, a new sensor data sink will be created with a new id.

8 Public Endpoints and Technical Specification

• Endpoint Production Base Url API https://apibridge.elpro.cloud

• For Developers the OpenAPI technical specification as Swagger UI https://apibridge.elpro.cloud/swagger