# REST-API

## REST-API

Übersicht über die BuildingPro Suites REST API Die BuildingPro Suites REST API ermöglicht den einheitlichen Zugriff auf die Ressourcen und Daten einer BuildingPro Suites-Umgebung. Die Beschreibung der API liegt im weit verbreiteten [OpenAPI](https://www.openapis.org/) Format vor und kann daher auf vielfältige Weise wiederverwendet werden.

[![](https://api.eliona.io/favicon-32x32.png)BuildingPro Suites API](https://api.eliona.io/)

Der [BuildingPro Suites App SDK](https://doc.eliona.io/collection/referenzen/app-sdk) stellt vorgefertigte Bibliotheken für verschiedene Programmiersprachen bereit, um über die API auf BuildingPro Suites zuzugreifen.

### Zugriff und Authentifizierung

Auf die BuildingPro Suites API kann über den URL-Pfad zugegriffen werden `/api/v2`. Wenn die URL für BuildingPro Suites beispielsweise `https://my.eliona.domain`lautet, wird auf die API über die folgende URL zugegriffen:

> `https://my.eliona.domain/api/v2`

Für die Authentifizierung wird ein API-Schlüssel verwendet. Dieser wird vom BuildingPro Suites-Administrator pro Anwendung ausgestellt und kann ein Ablaufdatum haben. Um ihn zu erstellen, muss bekannt sein, welche API-Endpunkte benötigt werden und ob Lese- oder Schreibzugriff gewährt werden soll. Der API-Schlüssel muss im HTTP-Header des Aufrufs als `X-Api-Key`:

```
GET https://my.eliona.domain/api/v2/assets/158
X-Api-Key: {{key}}
```

#### **Postman-Sammlung** mit Beispielen

Für einfache API-Tests steht eine Postman-Sammlung mit mehreren Anfragebeispielen zur Verfügung. Sie können die `postman_collection.json` -Datei direkt über die folgende URL in Postman importieren. Bevor Sie die Sammlung verwenden, stellen Sie sicher, dass Sie die `api-server` und `read-write-token` -Variablen an Ihre Umgebung anpassen.

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

### Clients für den API-Zugriff

**Clients für verschiedene Programmiersprachen**

Mit der OpenAPI-Beschreibung der Schnittstelle ist es möglich, mithilfe von geeignete Clients für eine Vielzahl von Programmiersprachen zu erstellen [OpenAPI-Generatoren](https://openapi-generator.tech/docs/generators). Für die Generierung stehen verschiedene Methoden zur Verfügung. Es wird empfohlen, das bereitgestellte Docker-Image zu verwenden. Dafür wird auf die neueste Version der OpenAPI-Beschreibung verwiesen:

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

Hier ist ein Beispielaufruf, um einen Client für die Programmiersprache Go zu generieren.

{% 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](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 ein Client stets aktualisiert und über GitHub bereitgestellt.

{% embed url="<https://github.com/eliona-smart-building-assistant/python-eliona-api-client>" %}
Python-Client für die BuildingPro Suites API
{% endembed %}

{% embed url="<https://github.com/eliona-smart-building-assistant/go-eliona-api-client>" %}
Go-Client für die BuildingPro Suites API
{% endembed %}

Postman: Importieren der API-Beschreibung

Die OpenAPI-Beschreibung der BuildingPro Suites REST-Schnittstelle kann in Postman importiert werden. Dadurch stehen alle Endpunkte für Abfragen zur Verfügung. Importieren Sie dazu die folgende URL in Postman:

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

<figure><img src="https://1888287146-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FB9s2DNtIvhBdrJ64xR9g%2Fuploads%2Fy06Xa74cDM69ZY7u8yJR%2Fimage.png?alt=media&#x26;token=e486405a-9a8e-4f83-ae20-02901d94af16" alt=""><figcaption></figcaption></figure>

Import-URL für den Workspace Nachdem die OpenAPI-Datei importiert wurde, stehen alle Endpunkte zur Verfügung. Um die API zu verwenden, muss der API-Schlüssel im Bereich "Authorization" und die jeweilige Basis-URL unter "Variables" eingetragen werden.

#### Mock für API-Tests

Ein entsprechender BuildingPro Suites-Mock steht zum Testen der API zur Verfügung. Dieser kann unabhängig von einer vollständigen BuildingPro Suites-Umgebung verwendet werden. Der Mock stellt eine vollständige API-Implementierung und eine vereinfachte BuildingPro Suites-Datenbank über ein Docker-Netzwerk bereit. Die passende `docker-compose.yml` und die Datenbankdefinition werden über GitHub bereitgestellt:

{% embed url="<https://github.com/eliona-smart-building-assistant/eliona-mock>" %}
BuildingPro Suites-Mock
{% endembed %}