...
Projekt/Produkt
...
ELPRO CLOUD
...
Ausgabe
...
Grundlegende REST-API für elproCLOUD
...
Version
...
1.0.0
1. Inhaltsverzeichnis
2. Wortlaut
...
Physikalisches Gerät
Ein physisches Gerät wird durch eine Seriennummer identifiziert und hat 1 bis n Kanäle.
Jeder Kanal kann unabhängig konfiguriert werden (z.B. eigenes Messintervall) und hat einen oder mehrere Sensoren, die 1 bis m verschiedene Sensorwerte liefern können.
Zum Beispiel;
...
ein Wert: Temperatur (für einen Temperatursensor)
...
zwei Tupel von: relative Feuchte und Temperatur (für einen rH-Sensor)
...
1. Table of Contents
Table of Contents | ||||
---|---|---|---|---|
|
...
2. General
2.1 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.
2.2 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.
2.3 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)
...
Virtuelle Darstellung mit alarmierender
In elproCLOUD haben wir eine Eins-zu-Eins-Zuordnung von Gerät und Kanal.
Für die Werte eines Sensors haben wir eine eins-zu-n-Zuordnung zu virtuellen Sensoren.
Ein virtueller Sensor wird für jede Konfiguration eines realen Sensors erstellt und dient dazu, verschiedene Arten von Alarmen mit demselben Sensorwert zu verbinden.
3. Kommunikationskonzept elproCLOUD <> externe Anwendung
...
REST-API für die Abfrage von Daten
Die Kommunikation zwischen der elproCLOUD und der externen Anwendung wird über eine REST-API realisiert 1<=2 und 4=>3. Die Schnittstelle 1<=2 wird verwendet, um Informationen von externen Anwendungen von der elproCLOUD anzufordern. Die Schnittstelle 4=>3 liefert Informationen, die von der externen Anwendung angefordert wurden.
Die Kommunikation läuft in der Regel in der folgenden Reihenfolge ab:
...
Das Gerät sendet seine Daten und Ereignisse in einem definierten festen Intervall an die elproCLOUD.
Es gibt Mechanismen, bei denen das Gerät seine Daten direkt an die elproCLOUD sendet und nicht auf das nächste Kommunikationsintervall wartet.
Die Kunden-App fordert die Daten von elproCLOUD über die REST-API bei Bedarf oder in einem selbst definierten Intervall an. Dieses Intervall sollte auf der Grundlage einer Risikoeinschätzung festgelegt werden.
4. Version der REST-API
Für die REST-API ist ein Versionierungsmechanismus implementiert.
Die Versionierung umfasst eine Major- und eine Minor-Nummer.
Major-Nummern stellen eine Schnittstelle zur elproCLOUD zur Verfügung und werden erhöht, wenn die Funktionalität der Schnittstelle drastisch verändert wird. Minor-Nummern werden erhöht, wenn der zurückgegebenen Datenstruktur Informationen hinzugefügt werden.
...
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.
2.4 Data format
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.
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.
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.
...
3. REST-API
...
The client can request information from elproCLOUD via REST-API. The communication runs typically in the following sequence:
The device will send its data and occurences in defined fix inteval to the elproCLOUD.
There are mechanisms, 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.
Info |
---|
Please be aware that some query results are limited |
Specification:
The Endpoint REST API URL https://apibridge.elpro.cloud
The API token is provided by ELPRO
For Developers the OpenAPI technical specification as Swagger UI https://apibridge.elpro.cloud/swagger
3.1 Data sets and general request scheme
The client can request different data sets, including
Measurements
Geodata
Occurences
Deviation
3.1.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:
EAPI-ELCLV2 | 123a45b67_SAMPLE_f12345ab6c789d0 |
In case of lack or mismatch, an Error message with HTTP Status 401 “Unauthorized” will be returned.
3.1.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).
3.1.3 Http Error Codes
400 Bad Request | e.g. missing mandatory parameter |
401 Unauthorized | Invalid or missing API Key |
404 Resource not found | Invalid serial number or id |
406 Not Acceptable | Accept Header should be only application/json |
410 License exhausted | Number of queries or datatransfer used up |
500 Server Error | Unexpected internal exception |
503 Service Temporarily Unavailable | Service down due to maintenance or update |
3.2 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.
Code Block | ||
---|---|---|
| ||
{
"version": "<Major.Minor>",
} |
5. Allgemein für alle Anfragen
5.1 Art des Sicherheitssystems
Zunächst richtet ELPRO einen API-Schlüssel für einen bestimmten Benutzer einer Organisation ein.
Geben Sie Ihren API-Autorisierungscode im Anfrage-Header als Schlüssel und Wert an:
...
EAPI-ELCLV2
...
Im Falle eines Fehlens oder einer Nichtübereinstimmung wird eine Fehlermeldung mit dem HTTP-Status 401 "Nicht autorisiert" zurückgegeben.
5.2 Benutzerumfang
Die abgerufenen Daten fallen in den Bereich der Organisation des authentifizierten API-Benutzers. Sie werden mit dem HTTP-Statuscode 200 (Erfolg) zurückgegeben.
5.3 Http-Fehler-Codes
...
400 Schlechte Anfrage
...
z.B. fehlender obligatorischer Parameter
...
401 Nicht autorisiert
...
Ungültiger oder fehlender API-Schlüssel
...
404 Ressource nicht gefunden
...
Ungültige Seriennummer oder ID
...
406 Nicht akzeptabel
...
Accept Header sollte nur application/json lauten
...
410 Lizenz erschöpft
...
Anzahl der verbrauchten Abfragen oder Datentransfers
...
500 Server-Fehler
...
Unerwartete interne Ausnahme
...
503 Dienst vorübergehend nicht verfügbar
...
Dienst aufgrund von Wartung oder Update nicht verfügbar
5.4 Schema für Anfrage und Antwort
Beachten Sie, dass jedes von der API akzeptierte und zurückgegebene JSON dem JSON-Standard entsprechen muss, wie er in der ECMA-404 Standard mit den folgenden Änderungen.
JSON-Eigenschaftsnamen sind case invariant und es kann keine Garantie für die Groß- und Kleinschreibung von Namen gegeben werden, die von der API zurückgegeben werden. Das bedeutet, dass kein Unterschied zwischen Groß- und Kleinbuchstaben in Eigenschaftsnamen gemacht wird.
Die relative Reihenfolge der JSON-Namen in Antworten kann nicht garantiert werden. Das bedeutet, dass Sie sich beim Parsen und Verarbeiten von Antworten nicht auf die Reihenfolge der Eigenschaften in den Antworten verlassen sollten.
6 Geräte
Die Darstellung der Geräte wird durch ihre eindeutigen Seriennummern identifiziert. Diese Datenobjekte enthalten eine Untergruppe von Informationen sowie eine Liste von SensorIds für Datensenken, die Messdaten enthalten. Mit dem angegebenen API-Schlüssel werden der Benutzer und die verknüpften Geräte identifiziert.
7 Sensoren
Sensoren stellen eine Datensenke dar, in der die Daten eines Laufs gespeichert werden. Jeder Sensor hat ein Start- und Enddatum. Seine Sensor-ID ist eindeutig und mit Messungen, Geolocation und Ereignisdaten verknüpft.
Sobald das Gerät neu gestartet wird, wird eine neue Sensordatensenke mit einer neuen ID erstellt.
8 Öffentliche Endpunkte und technische Spezifikation
...
Endpunkt Production Base Url API https://apibridge.elpro.cloud
...
4. Message Queue (AMQP)
...
A “Customer-Queue” is provided using AMQ protocol which is reachable under amqp.elpro.cloud.
The Queue-Name is the name of the explicitly provisioned RabbitMQ Queue. Queue and Users are managed by ELPRO.
Furthermore a unique username and password for every customer is provided. See below in this document for an example implementation.
Every customer can use his AMQP client of choice to read and acknowledge on the list of message types.
The connection is TLS only (Port 443)
In Production the Time to live (TTL) of queue data is set to three days.
4.1 Message Models
The Queue Messages will have following basic payload as JSON:
Fieldname | Type | Description |
type | String | Possible Message types:
|
data | JSON object | Inner JSON representation of an info message, see info data models later in this document |
4.2 Message Type
Each Type represents a dedicated json payload inside the Data JSON object. So a consumer knows which Data Model is used.
eapi_measurement_new
eapi_geodata_new
eapi_occurrence_new
eapi_deviation_enter
eapi_deviation_leave
4.3 Data Models
The Data payloads are different for each type.
4.3.1 Measurement
Fieldname | Type | Description |
sensorId | Int64 | Id for the sensor data representing a data sink. |
deviceId | String | Identifier of the device |
value | Decimal | Numeric value of the measure
|
timeStamp | DateTimeOffset | DateTime of measure as timezone utc |
unit | String | Unit Token Possible Values: K,°C,°F, % |
unitType | String | Type of unit as text:
|
4.3.1.1 Example Measurements
Data with type: “eapi_measurement_new”
Code Block | ||
---|---|---|
| ||
{
"type": "eapi_measurement_new",
"data": {
"timeStamp": "2022-10-11T16:21:27+00:00",
"value": 24.6,
"unit": "°C",
"unitType": “temperature",
"deviceId": "951FF00000340",
"sensorId": "5368"
}
} |
4.3.2 GeoData
Fieldname | Type | Description |
sensorId | Int64 | Id for the sensor data representing a data sink. |
deviceId | String | Identifier of the device |
latitude | Double | Latitude with 8 digits precision |
longitude | Double | Longitude with 8 digits precision |
timestamp | DateTimeOffset | datetime in timezone utc |
accuracy | Decimal | Accuracy in meters |
4.3.2.1 Example GeoData
Data with type: “eapi_geodata_new”
Code Block |
---|
{
"type": "eapi_geodata_new",
"data": {
"timeStamp": "2022-10-11T15:21:24+00:00",
"latitude": 47.19999075,
"longitude": 9.50875282,
"accuracy": 2316,
"deviceId": "951FF00000340",
"sensorId": "5369"
}
} |
4.3.3 Occurrence
Fieldname | Type | Description |
sensorId | Int64 | Id for the sensor data representing a data sink. |
deviceId | String | Identifier of the device |
timeStamp | DateTime | DateTime of occurrence as timezone utc |
typeName | String | "LoggerStatusChange” |
previousState | String | Possible values: "Undefined", "Init", "Shelflife", "Pairing", "Start", "LogDelayed", "LogTransit", LogPaused", "LogArrived", "StopStopped", "StopSleep", "Calibration", "EmergencyReadOut", "FatalError", "ProductionCalibration" |
newState | String |
4.3.3.1 Example Occurence
Data with type “eapi_occurrence_new”
Code Block | ||
---|---|---|
| ||
{
"type": "eapi_occurrence_new",
"data": {
"timeStamp": "2022-10-11T15:21:24+00:00",
"typeName": "LoggerStatusChange",
"previousState": "Start",
"newState": "LogDelayed",
"deviceId": "951FF00000340",
"sensorId": "5369"
}
} |
4.3.4 Deviation
Fieldname | Type | Description |
sensorId | Int64 | Id for the sensor data representing a data sink. |
deviceId | String | Identifier of the device |
timestamp | DateTimeOffset | DateTime of deviation as timezone utc |
historyType | String | Type of Deviation describring begin or end of deviation. Possible values: “enter” |
deviationType | String | Deviation type, possible values: "battery", |
reason | String | Deviation explanation code |
limitzone | String (opt.) | Limit Zone code for a limit deviation Possible values: L1,L2,L3, H1,H2,H3… |
4.3.4.1 Example Deviation Enter
Data with type “eapi_deviation_enter”
Code Block |
---|
{
"type": "eapi_deviation_enter",
"data": {
"deviceId": "951FF00000340",
"sensorId": 5763,
"timeStamp": "2022-10-26T17:00:22+00:00",
"historyType": "enter",
"deviationType": "limit",
"reason": "upper_limit_alarm"
}
} |
4.3.4.2 Example Devation Leave
Data with type “eapi_deviation_leave”
Code Block | ||
---|---|---|
| ||
{
"type": "eapi_deviation_leave",
"data": {
"deviceId": "951FF00000340",
"sensorId": 5763,
"timeStamp": "2022-10-26T18:00:22+00:00",
"historyType": "leave",
"deviationType": "limit",
"reason": "upper_limit_alarm"
}
} |
4.4 Consume AMQP Messages
4.4.1 Example Client Code with RabbitMQ in C#
Example Code how to connect to a Queue with .NET and RabbitMQ nuget library:
Code Block |
---|
public ObservableCollection<MessageModel> Messages { get; private set; }
public static IConnection connection;
public static IModel channel;
public static EventingBasicConsumer consumer;
public void Read()
{
var serverName = "amqp.elpro.cloud"
var queueName = "398ab9ae90efce88dcf623cc49e302e1";
bool autoACK = true;
try
{
// Prepare
var factory = new ConnectionFactory()
{
HostName = serverName,
UserName = "user",
Password = "password",
Port = 443,
Ssl = new SslOption()
{
Enabled = true,
ServerName = serverName
}
};
connection = factory.CreateConnection();
channel = connection.CreateModel();
var routingKey = $"*.eapi_*"; //*.eapi_measurement_new e.g.
Console.WriteLine(" [*] Waiting for msgs.");
// Consumer
consumer = new EventingBasicConsumer(channel);
consumer.Received += (model, ea) =>
{
var body = ea.Body.ToArray();
var messageText = Encoding.UTF8.GetString(body);
var message = new MessageModel(ea.RoutingKey, messageText);
Dispatcher.Dispatch(() => Messages.Add(message));
};
// Subscribe
channel.BasicConsume(queue: queueName,
autoAck: autoACK,
consumer: consumer);
}
catch (Exception ex)
{
Console.WriteLine($"Error at RabbitMQ.Test: {ex.Message}");
}
} |
...
5. Connection Details and Technical Specification
Endpoint REST API URL https://apibridge.elpro.cloud
AMQP Server: amqp.elpro.cloud
For Developers the OpenAPI technical specification as Swagger UI https://apibridge.elpro.cloud/swagger