REST-API

Überblick über die BuildingPro Suites REST-API Die BuildingPro Suites REST-API ermöglicht einen einheitlichen Zugriff auf die Ressourcen und Daten einer BuildingPro Suites-Umgebung. Die Beschreibung der API liegt im weit verbreiteten OpenAPI Format vor und kann daher auf vielfältige Weise wiederverwendet werden.

BuildingPro Suites API

Das BuildingPro Suites 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 die API über die folgende URL erreichbar:

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

Zur Authentifizierung wird ein API-Schlüssel verwendet. Dieser wird vom BuildingPro-Suites-Administrator pro Anwendung ausgestellt und kann ein Ablaufdatum haben. Bei der 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-Collection mit Beispielen

Eine Postman-Collection mit mehreren Anfragebeispielen steht für einfache API-Tests zur Verfügung. Sie können die postman_collection.json Datei direkt über die folgende URL in Postman importieren. Stellen Sie vor der Verwendung der Collection sicher, dass Sie die api-server als auch 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 lassen sich geeignete Clients für eine Vielzahl von Programmiersprachen mithilfe von OpenAPI-Generatoren. Verschiedene Methoden stehen für die Generierung zur Verfügung. Es wird empfohlen, das bereitgestellte Docker-Image zu verwenden. Auf die neueste Version der OpenAPI-Beschreibung wird hierfür 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.

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"

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

Postman: Import der API-Beschreibung

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

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

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 unter dem Abschnitt "Authorization" und die jeweilige Basis-URL unter "Variables" eingetragen werden.

Mock für API-Tests

Für das Testen 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 bietet eine vollständige API-Implementierung und eine vereinfachte BuildingPro Suites-Datenbank mithilfe eines Docker-Netzwerks. Das passende docker-compose.yml und die Datenbankdefinition werden über GitHub bereitgestellt:

VorherigePartner-Studio-Leitfaden

NächsteEngineering

Zuletzt aktualisiert vor 5 Monaten

War das hilfreich?