# 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](https://www.openapis.org/) vor und kann somit auf vielfältige Weise weiterverwendet werden.
[Eliona API](https://api.eliona.io/)
Das [Eliona App SDK](https://doc.eliona.io/collection/referenzen/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 : {{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.
>
### Clients für den Zugriff auf die API
**Clients für unterschiedliche Programmiersprachen**
Mit der OpenAPI-Beschreibung der Schnittstelle ist es mittels [OpenAPI-Generatoren](https://openapi-generator.tech/docs/generators) 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:
>
Hier ein beispielhafter Aufruf zur Generierung eines Clients für die Programmiersprache Go.
{% code lineNumbers="true" %}
```bash
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"
```
{% endcode %}
Für die Programmiersprachen Go und Python wird derzeit immer ein Client aktualisiert und über GitHub bereitgestellt.
{% embed url="" %}
Python Client für Eliona API
{% endembed %}
{% embed url="" %}
Go Client für Eliona API
{% endembed %}
**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:
>
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:
{% embed url="" %}
Eliona-Mock
{% endembed %}
