# REST-API

## REST-API

Überblick ü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/)

Die [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

Die BuildingPro Suites API ist über den URL-Pfad erreichbar `/api/v2`. Wenn beispielsweise die URL für BuildingPro Suites `https://my.eliona.domain`lautet, ist die API über die folgende URL erreichbar:

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

Zur Authentifizierung wird ein API-Schlüssel verwendet. Dieser wird pro Anwendung vom BuildingPro Suites-Administrator ausgestellt und kann ein Ablaufdatum haben. Zur Erstellung 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 einfaches API-Testing steht eine Postman-Sammlung mit mehreren Anfragebeispielen zur Verfügung. Sie können die `postman_collection.json` Datei direkt in Postman über die folgende URL 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 [OpenAPI-Generatoren](https://openapi-generator.tech/docs/generators)geeignete Clients für eine Vielzahl von Programmiersprachen zu erstellen. Für die Generierung stehen verschiedene Methoden zur Verfügung. Empfohlen wird die Verwendung des bereitgestellten Docker-Images. 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 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](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 stets ein Client 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: Import der API-Beschreibung

Die OpenAPI-Beschreibung der BuildingPro Suites REST-Schnittstelle kann in Postman importiert werden. Dadurch sind alle Endpunkte für Abfragen verfügbar. 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, sind alle Endpunkte verfügbar. Um die API zu verwenden, muss der API-Schlüssel im Abschnitt "Authorization" und die jeweilige Basis-URL unter "Variables" eingetragen werden.

#### Mock für API-Tests

Für Tests der API steht ein entsprechender BuildingPro Suites-Mock 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.buildings.ability.abb/collection/german/for-developers/rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.