REST API

REST API

Überblick über die Eliona REST APIDie Eliona REST API ermöglich einen einheitlichen Zugriff auf die Ressourcen und Daten einer Eliona Umgebung. Die Beschreibung der API liegt im weit verbreiteten Format OpenAPI vor und kann somit auf vielfältige Weise weiterverwendet werden.

Eliona API

Das Eliona App SDK ermöglicht mit vorgefertigten Bibliotheken für unterschiedliche Programmiersprachen den Zugriff auf Eliona über die API.

Zugriff und Authentifizierung

Die Eliona API kann man über den URL-Pfad /api/v2 erreichen. Lautet die URL für Eliona beispielsweise https://meine.eliona.domain, dann erreicht man die API über folgende URL:

https://meine.eliona.domain/api/v2

Für die Authentifizierung ist ein API-Key zu verwenden. Dieser wird pro Anwendung vom Administrator von Eliona ausgestellt und kann mit einem Ablaufdatum versehen sein. Für die Erstellung muss bekannt sein, welche Endpunkte der API benötigt werden und ob darüber lesende oder schreibende Zugriffe erfolgen sollen.Der API-Key ist im HTTP-Header des Aufrufs als X-Api-Key mitzuliefern:GET https://meine.eliona.domain/api/v2/assets/158X-Api-Key: {{key}}

Postman Collection mit Beispielen

Eine Postman-Collection mit mehreren Anforderungsrequests steht für einfaches API-Testing zur Verfügung. Sie können die Datei postman_collection.json direkt in Postman über die folgende URL importieren. Bevor Sie die Sammlung verwenden, stellen Sie sicher, dass Sie die Variablen api-server und read-write-token entsprechend Ihrer Umgebung aktualisieren.

https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/refs/heads/main/examples/postman-collection.json

Clients für den Zugriff auf die API

Clients für unterschiedliche Programmiersprachen

Mit der OpenAPI-Beschreibung der Schnittstelle ist es mittels OpenAPI-Generatoren möglich passende Clients für die verschiedensten Programmiersprachen zu erstellen.Für die Generierung stehen unterschiedliche Methoden zur Verfügung. Es empfiehlt sich das bereitgestellte Docker-Image zu verwenden. Dazu wird die jeweils aktuelle Version der OpenAPI-Beschreibung referenziert:

​https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/main/openapi.yaml​

Hier ein beispielhafter Aufruf zur Generierung eines Clients für die Programmiersprache Go.

docker run --rm \
     -v "${PWD}:/local" \
     openapitools/openapi-generator-cli:v6.2.1 generate \
     -g go \
     -i https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/main/openapi.yaml \
     -o /local \
     --additional-properties="packageName=api"

Für die Programmiersprachen Go und Python wird derzeit immer ein Client aktualisiert und über GitHub bereitgestellt.

GitHub - eliona-smart-building-assistant/python-eliona-api-client: Python API client for Eliona App SDKGitHub

Python Client für Eliona API

GitHub - eliona-smart-building-assistant/go-eliona-api-client: Go API client for Eliona App SDKGitHub

Go Client für Eliona API

Postman: Import der API-Beschreibung

Die OpenAPI-Beschreibung der Eliona REST-Schnittstelle kann in Postman importiert werden. Somit stehen alle Endpunkte für die Abfrage zur Verfügung. Dazu ist folgende URL in Postman zu importieren:

​https://raw.githubusercontent.com/eliona-smart-building-assistant/eliona-api/main/openapi.yaml​

​​

Import URL für WorkspaceNachdem die OpenAPI-Datei importiert wurde, stehe alle Endpunkte zur Verfügung. Damit API verwendet werden kann, muss unter dem Punkt Authorization der API-Key und unter Variables die jeweilige Basis-URL eingetragen werden.

Mock für API Tests

Für den Test mit der API steht eine entsprechender Eliona-Mock zur Verfügung. Dieser kann losgelöst von einer vollständigen Eliona-Umgebung genutzt werden. Der Mock stellt eine vollständige API-Implementierung und eine vereinfachte Eliona-Datenbank mittels Docker-Netzwerk zur Verfügung. Die passende docker-compose.yml und die Datenbankdefinition wird über GitHub bereitgestellt:

GitHub - eliona-smart-building-assistant/eliona-mock: Mocks an Eliona environmentGitHub

Eliona-Mock