REST API
Last updated
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.
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}}
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.
Für die Programmiersprachen Go und Python wird derzeit immer ein Client aktualisiert und über GitHub bereitgestellt.
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:
