Funktionsbeschreibung http-Rest Schnittstelle

Mit dieser Schnittstelle können Sie von einer externen Anwendung aus per HTTP bestimmte Werte aus dem LOGIKEDITOR abfragen, oder Werte an den LOGIKEDITOR senden.

Dazu legen Sie in der Datenpunktverwaltung HTTP-Datenpunkte an, konfigurieren den jeweiligen Datentyp sowie die erlaubten Operationen und vergeben optional "sprechende Pfade". In Ihren Logikgruppen fügen Sie dann Werteeingänge bzw. Werteausgänge für den entsprechenden HTTP-Datenpunkt hinzu. Je nachdem wie Sie den Signalverlauf in der Logikgruppe gestalten, können Sie somit z.B. per HTTP-Anfrage an den LOGIKEDITOR Werte auf den KNX-Bus senden oder beliebige Aktionen im LOGIKEDITOR ausführen wie z.B. den Freigabeeingang eines Logikelements schalten oder den Status eines Wertespeichers auslesen.

Für die Abfrage externer HTTP-Schnittstellen aus dem LOGIKEDITOR heraus, also den umgekehrten Anwendungsfall, benutzen Sie das Logikelement HTTP-Abfrage.

Inhalt

Unterstützte Protokolle

• https (Port 444)

• http (Port 81)

https wird durch ein von der BAB TECHNOLOGIE GmbH selbst signiertes Zertifikat autorisiert. Gegebenenfalls muss die Unterstützung selbst signierter Zertifikate bei der externen Anwendung erst aktiviert werden, oder wird nicht unterstützt. Informieren Sie sich bei Problemen hierzu bitte individuell für Ihren Anwendungsfall. Auch mit selbst signiertem Zertifikat ist https deutlich sicherer als http, weil die Verschlüsselung in jedem Fall gewährleistet ist.

http wird nicht empfohlen, da Authentifizierungsdetails dann in jedem Fall unverschlüsselt übertragen werden. Wir bieten http nur für den Fall an, dass die externe Anwendung gar kein https oder keine selbstsignierten Zertifikate unterstützt, eine Integration aber unbedingt gewünscht ist.

Unterstützte Methoden

• GET
  zum Auslesen von Werten aus dem LOGIKEDITOR

• POST oder PUT
  zum Setzen von Werten im LOGIKEDITOR, wobei der aktuell gültige Wert auch gleich als Body in der Antwort übermittelt wird.

Sie haben in der Konfiguration eines Datenpunkts die Möglichkeit, das Lesen und Setzen des Wertes individuell frei zu geben. Anfragen mit Methoden für die der jeweiligen Datenpunkt nicht frei gegeben wurde, führen zu einer Antwort mit Statuscode 403 (siehe unten).

Sollten Sie für das Setzen von Werten den zulässigen Wertebereich einschränken wollen, so nutzen Sie bitte einfach z.B. das Filter-Tool nachgelagert hinter dem entsprechenden Werteeingang für diesen Datenpunkt in Ihrer Logikgruppe.

Unterstützte Authentifizierung

Die Authentifizierung erfolgt optional, wird aber empfohlen, mit statischen Tokens. Das bedeutet, dass die externe Anwendung bei aktivierter Authentifizierung eine feste, geheime Zeichenkette mit übermitteln muss, damit die Anfrage zugelassen wird.

Die Übermittlung des Tokens kann auf zwei Wegen erfolgen

• mittels Authorization Header. Unterstützt wird dabei als Header-Wert sowohl das sogenannte Bearer-Schema als auch das reine Token.

• als URL-Parameter token

Die Übermittlung als URL-Parameter wird nicht empfohlen, da eine URL, im Gegensatz zu Headern, selbst bei Nutzung von https unverschlüsselt übertragen wird.
Angreifer im gleichen Netz könnten das Token in diesem Fall also auslesen und dann selbst Anfragen senden. Wir bieten diese Methode nur für den Fall an, dass die externe Anwendung keine einstellbaren Header anbietet, eine Integration aber unbedingt gewünscht ist.

Sie können ein Token als Standard für alle Datenpunkte konfigurieren. Sie können aber auch den Datenpunkten individuelle Tokens zuweisen. Unsere Empfehlung ist es, mindestens für jede externe Anwendung ein individuelles Token zu erstellen. Auch eine Unterscheidung von Tokens für Lese- bzw. Schreibzugriff kann sinnvoll sein.

Beispiel:
Sie haben eine Webcam die per LOGIKEDITOR REST-API bei Bewegung das Licht einschalten soll und schützen diesen Datenpunkt mit Token 1, und Sie haben einen smarten Rasenmäher, der per REST-API einen Datenpunkt schalten soll wenn ein Problem mit dem Gerät vor liegt. Diesen Datenpunkt schützen Sie mit Token 2. Sollte jemand unbefugten Zugriff auf die Webkonfiguration des Rasenmähers erhalten, dann kann er mit dem dort hinterlegten Token 2 nicht das Licht einschalten.

Eine hohe Anzahl von Requests mit fehlendem oder falschem Token führen zu der temporären Aussperrung mit steigender Aussperrzeit (Antwort mit Statuscode 429, siehe unten).

Aufbau der URL

Die REST-URL für einen Datenpunkt ergibt sich aus der Kombination von Basis-URL sowie dem URL-Anteil des Datenpunktes.

Basis-URL

Die REST-Schnittstelle erreichen Sie, je nachdem ob Sie https oder http benutzen, über:

• https:

• CODE

  https://<IP-Addresse des EIBPORT>:444/le/rest/

• http:

• CODE

  http://<IP-Addresse des EIBPORT>:81/le/rest/

URL-Anteil des Datenpunktes

Jeder Datenpunkt hat eine zufällige Identifikationszeichenkette, eine sogenannte UUID. Sie können für die URL immer direkt seine UUID nutzen, oder aber zusätzlich einen individuellen Pfad vergeben.

Prinzipiell ist hier jede Art von Struktur denkbar. Es böte sich z.B. an, die Pfade anhand der Gebäudetopologie und Geräte aufzubauen. Bedenken sollte man aber, dass solche beschreibenden URLs eben auch Details über die realisierte Funktion beziehungsweise private Informationen über Haus und Bewohner preisgeben könnten.

Beispiele:
https://192.168.1.21:444/le/rest/og/zimmer-lena/deckenleuchter/schalter

https://192.168.1.21:444/le/rest/lamps/01

https://192.168.1.21:444/le/rest/41611b55-b54d-4b0a-a36d-aa9ba766a163

http://192.168.1.21:81/le/rest/41611b55-b54d-4b0a-a36d-aa9ba766a163?token=geheim
(unsicher, weil http und Token in der URL)

Datenformat der Schnittstelle

Das Datenformat ist aus 3 Formaten wählbar, und sogar bei Bedarf pro Datenpunkt einstellbar, z.B. wenn Sie mehreren externe Anwendungen Zugriff erlauben möchten, und eine nur JSON, eine andere aber nur Text unterstützt:

• JSON
  Json-Objekt mit einem Paar, bzw. bei komplexen Datenpunkten mehreren Paaren, aus Bezeichner und Wert. Die Bezeichner konfigurieren Sie selbst im Datenpunkt.
  Beispiel:

  CODE

  {
     "red": 128,
     "green": 128,
     "blue": 128
  }

• CSV
  Eine Zeile kommaseparierter Werte ohne Bezeichner (sofern es sich um einen komplexen Datenpunkt handelt, sonst nur genau ein Wert).
  Beispiel:

  CODE

  128;128;128

• Text
  Ein Wert des Datenpunktes je Zeile (ohne Bezeichner). Kein abschließender Zeilenumbruch.
  Beispiel:
  128
128
128

Das konfigurierte Datenformat gilt für den Antwort-Body von lesenden GET- und den Anfrage-Body von schreibenden POST/PUT-Aufrufen gleichermaßen. Bei einem schreibenden Aufrufen an einen Datenpunkt mit komplexem Datentyp (wie hier im Beispiel RGB) müssen immer aller Werte des Datenpunktes gesendet werden, andernfalls erhalten Sie als Antwort den Fehlercode 422 (siehe unten).

Welches Format Sie wählen sollten hängt davon ab, was die aufrufende Seite unterstützt, und wie übersichtlich Ihre Integration sein soll. Text und CSV sind ein klein wenig performanter als JSON, dafür bietet JSON eben bessere Verständlichkeit, gerade bei Datenpunkten mit komplexen Datentypen.

Antwort

Mögliche Status-Codes:

Header-Informationen

Mögliche Status-Codes:

Body

Der Body der Antwort im Erfolgsfall entspricht exakt dem Datenformat wie oben beschrieben, je nachdem welches Format Sie konfigurieren. Im Fehlerfall ist er meistens leer. Nur bei einer POST/PUT-Anfrage die Fehler 422 erzeugt, wird im Body der weiterhin gültige Wert auf dem Datenpunkt ausgegeben.

///