HTTP-API / REST-API Funktionen des Timberwolf Servers
- Stefan Werner (Org-Admin)
Schnellübersicht
Leistungsmerkmale ohne Limits
Der Timberwolf Server ermöglicht die besonders einfache Integration von Geräten und Servern, die Funktionen über HTTP-/REST-API zur Verfügung stellen durch die Unterstützung aller gängigen Protokollvarianten und Datenformate mit vielfältigen Konfigurationsmöglichkeiten und umfangreicher Diagnoseunterstützung.
Unterstützte HTTP Protokolle: HTTP, HTTPS und HTTP/2 (wird automatisch erkannt)
Unterstützte Kompressionsalgorithmen: gzip, compress, deflate, bzip2 (wird automatisch erkannt)
Unterstützte Verschlüsselung: TLS 1.1, TLS 1.2 (wird automatisch erkannt)
Zertifikatsprüfung bei verschlüsselten Verbindungen: Jeweils pro Ressource zuschaltbar
Unterstützte Authentifizierungen: Basic Authentication, API-Key (in den drei Varianten im Header, in der URI, im Body), Bearer Token
Parallele HTTP Subsysteme: Es können beliebig* viele HTTP-Subsysteme eingerichtet und parallel zueinander betrieben werden. Für jedes Subsystem können getrennte Timeouts eingerichtet werden. Jedes Subsystem zeichnet seine Statistik in Zeitserien für eine optimale Diagnose bei Nichterreichen von externen Ressourcen auf.
Unbeschränkte Anzahl angesprochener Server und Ressourcen: Über alle HTTP-Subsysteme hinweg können beliebig* viele Server, Geräte und deren Ressourcen angesprochen werden. Keine künstliche Grenze.
Unbeschränkte Anzahl von Datenpunkten: Die Anzahl der maximal konfigurierbaren Datenpunkte ist nicht durch eine künstliche Grenze beschränkt*.
Einfache Einrichtung durch grafische Benutzeroberfläche: Die Einrichtung der Funktionen erfolgt über eine responsive Web-APP, die mit fast jedem Endgerät mit Browser genutzt werden kann. Die Einrichtung wird unterstützt durch leicht bedienbare Assistenten, interaktive Hilfetexte, Plausibilitätsprüfungen und eine kontextsensitive Online-Hilfe sowie Diagnose-Anzeigen im Kommunikationsmonitor und Rückmeldungen in Echtzeit.
Konvertierung und Umrechnung von Datenformaten: Die im Body übermittelten Datenformate lassen sich fast beliebig in die internen Datenformate des Timberwolf Servers konvertieren. Dies ist auch in umgekehrter Richtung beim Übertragen von Werten auf die HTTP-/REST-API Ressource möglich.
Beliebige Verknüpfungen der Datenpunkte: Jeder HTTP-/REST-API Datenpunkt kann im Timberwolf Server fast beliebig* mit jedem anderen Datenpunkt in einer n:m Beziehung verknüpft werden. Damit können diese Datenpunkte mit vielen anderen Datenpunkten gleicher oder anderer Technologien wie z.B. KNX, 1-Wire, DMX, Zeitserien, Logik, Visu. MQTT, Modbus, HTTP-/REST-API, UDP/TCP, ekey sowie über IFTTT mit Produkten von 650+ Herstellern usw. verbunden werden. Mit nur drei Klicks.
Automatische Konvertierung: Konvertierungen von Datentypen bei Verknüpfung zu anderen Protokollen und Diensten erfolgen weitgehend automatisch.
Datenaustauschoptionen
HTTP Request: Methoden, Content Type und Datentypen
HTTP Request - Methoden:
GET
POST
HTTP Request - Content Type (nur POST):
text/plain
application/json
application/x-www-form-urlencoded
HTTP Request - Datentypen:
Bool
Ganzzahl,
vorzeichenbehaftete Ganzzahl
Fließkomma
Text
Diese Datentypen können, auch gemischt, in form-urlencoded oder JSON Datenstrukturen eingebettet sein
HTTP Request: Authentifizierung
HTTP Request - Authentifizierung mit “Basic Authentication”:
Username & Passwort
nur Passwort
HTTP Request - Authentifizierung mit “Bearer Token”: Bearer im Header
HTTP Request - Authentifizierung mit “API-Key”:
Übergabe API-Key in URI
Übergabe API-Key im Header
Übergabe API-Key im Body
HTTP Request: Wertübergaben in der URI
HTTP Request mit einzelnen oder mehreren Objektwerten in der URI: Es können einzelne oder mehrere Objektwerte in der URI übergeben werden. Hierzu ist der jeweilige Schlüssel (Bezeichnung des Headerfeldes) und das Objekt anzugeben, dessen Werte übergeben werden sollen.
Übergabe innerhalb der URI (an festlegbarer Stelle) im Format Schlüssel=Objektwert
Übergabe als Query-Parameter im Format Schlüssel=Objektwert
HTTP Request: Wertübergaben im Request Header
HTTP Request mit einzelnen oder mehreren Objektwerten im Header: Es können einzelne oder mehrere Objektwerte als Headerfelder übergeben werden. Hierzu ist der jeweilige Schlüssel (Bezeichnung des Headerfeldes) und das Objekt anzugeben, dessen Werte übergeben werden sollen.
HTTP Request: Wertübergaben Body (nur POST)
HTTP Request mit Übergabe einzelner Objektwert: Ein einzelner Objektwert kann per text/plain im Body übergeben werden.
HTTP Request mit Übergabe einzelner oder mehrerer Objektwerten (x-www-form-urlencoded): Es können einzelne oder mehrere Objektwerte übergeben werden, hierbei ist der jeweilige Schlüssel anzugeben sowie das Objekt, dessen Wert zusammen mit dem Schlüssel übergeben wird.
Bei dieser Kodierung werden Schlüssel-Wert-Paare hintereinander in einen langen String geschrieben. Die Schlüssel-Werte-Paare sind voneinander mit ampersand (“&”) getrennt und der Schlüssel vom Wert mit einem Ist-Zeichen (“=”). Der String wird URL-encoded (“Prozentkodierung” ähnlich RFC 3986).HTTP Request mit Übergabe einzelner oder mehrerer Objektwerten (application/json): Der Inhalt eines oder mehrerer Objektwerte kann per JSON Datenstruktur im Request Body an die Ressource gesendet werden. Die JSON Struktur darf dabei fast beliebig ineinander verschachtelt sein. Mehrere Auslöseoptionen erlauben die Steuerung des Zeitpunktes des Requests. Damit kann der Inhalt auch mehrerer Objektwerte zusammen in einer Datenstruktur an die Ressource gesendet werden.
HTTP Request: Auslösung
Zeitliche Auslöser für HTTP Request: HTTP Requests lassen sich in regelmäßigen Intervallen auslösen. Dies kann mit bedingten Auslösern kombiniert werden.
Bedingte Auslöser für HTTP Request: HTTP Requests lassen sich durch Bedingungen, z.B. Wertänderung einzelner Objektwerte sowohl für die jeweilige einzelne Transaktionen als auch gemeinsam für die gesamte Transaktionsgruppe - sowie Kombinationen daraus - auslösen. Hierüber kann granular gesteuert werden, welche Objektwertänderungen einen HTTP Request auslösen und welche Objektwerte dabei übertragen werden. Dies kann mit zeitlichen Auslösern kombiniert werden.
HTTP Response: Content Type und Datentypen
HTTP Response Content Type:
text/plain
application/json
Dekodierbare Datentypen:
Bool
Ganzzahl,
vorzeichenbehaftete Ganzzahl
Fließkomma
Text
Diese Datentypen können, auch gemischt, in JSON Datenstrukturen eingebettet sein
HTTP Response: Wertübernahme aus Body
HTTP Response mit Einzelwertübergabe: Einzelne Werte können per text/plain empfangen und an ein Objekt übergeben (und von dort beliebig weitergeleitet) werden.
HTTP Response mit Selektion mehrerer Werte aus JSON im Body: Beliebige Werte aus empfangenen JSON Datenstrukturen, auch mehrfach verschachtelt, können für die Zuweisung zu HTTP-/REST-API Objekten selektiert werden. Damit können Daten aus JSON Datenstrukturen in verschiedene Objekte vereinzelt und damit leicht gehandhabt werden.
Statusobjekte
Statuseigenschaften über Objekte: Statusobjekte stellen Statusrückmeldungen jeder einzelnen Transaktion sowie davon getrennte auch Ausgewertet nach Warnungen und Fehlern zur Verfügung. Damit kann eine dauerhafte Überwachung mit wenigen Klicks implementiert und Statusmeldungen auch in Logiken verarbeitet werden.
Fünf Statusobjekte: Für jede eingerichtete Ressource werden automatisch fünf Statusobjekte anlegt, die ebenso beliebig wie andere Objektwerte verknüpft werden können:
Request Warnung aufgetreten (Boolesch)
Request Fehler aufgetreten (Boolesch)
Request Fehler Status Code (Integer, HTTP Fehler Status Code)
Request Fehler Status Massage (Text, HTTP Fehler Status Massage)
Request Status Code (Integer, jeder HTTP Status Code)
HTTP-/REST-API Funktionsmodule des Timberwolf Servers
Verwaltung der HTTP-API Subsysteme
Das Management der HTTP-/REST-API Subsysteme erfolgt mit der grafischen Web-APP, die mit praktisch allen Browsern auf fast allen Endgeräten genutzt werden kann.
Zeitlimit für Verbindungen: Für jedes HTTP-/REST-API Subsysteme kann ein Zeitlimit angelegt werden. Durch das Anlegen mehrerer Subsysteme ist eine einfache Trennung zwischen internen und externen HTTP-API Ressourcen möglich. Damit können API-Abfragen interner Systeme (z.B. Ladestationen) in einem separaten Task bearbeitet werden gegenüber Abfragen externer Server (z.B. Ressourcen im Internet).
Verbindungsstatistik: Für jedes angelegte Subsystem wird automatisch eine Statistik über erfolgreiche und fehlerhafte Transaktionen bereitgestellt, die auch mit Grafana ausgewertet werden kann.
HTTP-API Server und Ressourcen Manager
Der HTTP-API Server und Ressourcen Manager ist das Modul in der Web-APP zum Anlegen und Verwalten der Transaktionen für den Datenaustausch mit den angelegten Servern und deren Ressourcen. Dies erfolgt über eine grafische Benutzeroberfläche und für alle Konfigurationsaufgaben mit Hilfe einfach bedienbarer Assistenten und dazu eingeblendeten kontextsensitiven Hilfetexten.
HTTP-API Server anlegen: Der HTTP-API Server und Ressourcen Manager ermöglicht das einfache Anlegen von Einträgen über die anzusprechenden Server mit HTTP-API.
Fixe Header zu HTTP-API Server konfigurieren Zu jedem HTTP-API Server Eintrag können statische Header-Felder hinzugefügt werden um den Erfordernissen der jeweiligen Server zu entsprechen.
HTTP-API Ressource hinzufügen: Zu jedem HTTP-API Server können ein oder mehrere Ressourcen angelegt werden. Für jede Ressource kann eine URI, ein zeitlicher Auslöser sowie die Request-Methode nebst den Content-Typen angelegt werden. Unterstützt wird:
Abfragemethode GET
Abfragemethode POST
HTTP-Requests und optional bedingte Auslöser hinzufügen: Zu jedem HTTP-API Ressourceneintrag können beliebig viele Objekte zur Übergabe bei einer HTTP-Abfragen hinzugefügt werden (= “Transaktion”). Für jede Wertübergabe kann konfiguriert werden:
Übertragung von Objektwerten an die Ressource in der URI (eingebettet)
Übertragung von Objektwerten an die Ressource als Query-Parameter (angehängt an die URI)
Übertragung von Objektwerten an die Ressource im Header (auch statische Header-Werte möglich)
Übertragung von Objektwerten an die Ressource im Body (nur POST), hierbei in den Formaten
text/plain (nur einzelner Objektwert)
application/json (einzelne und mehrere Objektwerte)
application/x-www-form-urlencoded (einzelne und mehrere Objektwerte)
Die Übertragung innerhalb URI, als Query-Parameter, im Header und im Body können gemischt angelegt und gleichzeitig in derselben Abfrage ausgeführt werden.
Für jede Wertübergabe kann eine physikalische Einheit und der Objekttyp (Boolesch, Ganzzahl, Fließkomma, Text) angegeben werden.
Für Übergabe im Body per application/json kann Schlüsselbegriff und Position im json angegeben werden, das json wird vom Subsystem automatisch erzeugt und kann im Datenmonitor geprüft werden
Für Übergabe im Body per application/x-www-form-urlencoded kann der Schlüsselbegriff angegeben werden, der entsprechende String wird vom Subsystem automatisch erzeugt und kann im Datenmonitor geprüft werden
Für jeden Transaktionseintrag kann ein bedingter Auslöser (um den HTTP-Request auszuführen) angegeben werden, z.B. bei Wertänderung und ob nur die einzelne Transaktion oder alle Transaktionen der Request-Gruppe ausgeführt werden sollen. Damit ist eine granulare Steuerung der Parameterübergabe und welche Parameter davon diese Übertragung auslösen möglich. Dies kann mit dem zeitlichen Auslöser für diese Ressource kombiniert werden.
HTTP-Response Auswertung mit Übergabe an Objekte: Zu jedem HTTP-API Ressourceneintrag können beliebig viele Auswertungen der HTTP-Antwort hinzugefügt werden (= “Transaktion”) mit der Werte aus dem Body in einzelne Werte zerlegt und an Objekte übergeben werden
Empfang einzelner Objektwerte in Body mit text/plain
Empfang einzelner oder mehrerer Objektwerte in Body mit application/json
Objektverknüpfungen inkl. Konvertierung: Beliebige Verknüpfung der angelegten HTTP-/REST-API Objekte (auch der Statusobjekte) mit allen anderen Objekten im Timberwolf Servers (z.B. Zeitserien, KNX, 1-Wire, DMX, Logik, Modbus Systeme, MQTT Geräte, Modbus Geräte, andere HTTP-/REST-API Objekte, IFTTT usw.) inkl. automatischer Konvertierung.
Ausführungsanzeige mit historischem Verlauf: Für alle Transaktionen steht eine Anzeige der Bearbeitungshistorie zur Verfügung mit farblich markiertem Status und Mouse-Over Detail-Info
Statusanzeige mit historischem Verlauf: Zusätzlich werden pro angelegter Ressource automatisch Statusobjekte zur Verfügung gestellt, die jederzeit aufgeklappt werden können. Auch diese Statusobjekte sind mit einer Anzeige der Historie mit farblicher Darstellung und Mouse-Over-Details ausgeführt.
Ausführliche Fehlerdarstellung mit Handlungsempfehlung: Fehlerrückmeldungen der HTTP-API Server werden dargestellt mit Handlungsempfehlungen für einfache Fehlerbehebung.
Anzeige der Live-Werte während der Ausführung: Die während der Transaktionen mit den HTTP-API Servern ausgetauschten Werte werden Live im Datenmonitor dargestellt.
Sofortstart hinzugefügter Applikationen: Neu hinzugefügte Transaktionen werden nach Definition sofort gestartet und eingebunden.
TAGs für beliebige Gruppierungen von Geräten und Applikationen: HTTP-API Server und Transaktionseinträge können mit TAGs für beliebige Gruppierungen markiert werden
Unterstützung von URI-Strukturen in mehreren Leveln über Assistenten: Die einzelnen Bestandteile der URL werden vom Subsystem automatisch zusammengesetzt aus der Host-Adresse, der URI der jeweiligen Ressource, den Einfügungen in der URI für API-Key und allen Wertübergaben in der URI sowie den Wertübergaben im Query-Abschnitt. Für alle Eingaben stehen einfach bedienbare grafische Assistenten zur Verfügung.
Assistenten mit interaktiven Hinweistexten: Alle Assistenten blenden kontextsensitiv Hilfetexte ein. Für weitere Details sind entsprechende Links zu diesem Wiki enthalten.
Farbcodierungen
Um Anzeigen und Funktionen voneinander besser abzugrenzen und insbesondere um Verwechselungen zu vermeiden, werden die URIs farblich anders dargestellt als die Objekte mit denen diese verbunden sind, zudem sind Übertragungs- und Empfangsrichtung farblich und mit Pfeilen gekennzeichnet.
HTTP-/REST-API URIs in Violett: Die URIs der Server und Ressourcen werden im HTTP-API Server und Ressourcen Manager und dessen Assistenten in violett dargestellt. Platzhalter für API-Key und Wertübergaben innerhalb der URI in rot. Die Host-Adresse wird invers dargestellt für eine bessere Lesbarkeit.
Auswertende Transaktionen für den Empfang (“HTTP Response”) sind Grün unterlegt: Die Definition für die Auswertung der von den jeweiligen Ressourcen zurückgegebenen Antworten sind mit grüner Farbe unterlegt und mit einem Pfeil von links nach rechts gekennzeichnet. Die entsprechenden Assistenten sind ebenfalls mit grün unterlegt.
Aufrufende Transaktionen für das Übergeben von Werten (“HTTP Request”) sind Blau unterlegt: Die Definition für die Übergaben im HTTP-API Server und Ressourcen Manager sind mit blauer Farbe markiert und mit einem Pfeil von rechts nach links gekennzeichnet. Die entsprechenden Assistenten sind ebenfalls blau unterlegt.
Statusobjekte für Transaktionen sind Gelb unterlegt: Für jede Ressource werden automatisch fünf Transaktionen mit Statusobjekten angelegt mit Warnungen, Fehlern und Stati.
Transaktionswarnungen in Gelb: Alle Stati mit dem Schweregrad “Warnungen” werden gelb markiert
Transaktionsfehler in Rot: Diejenigen Rückmeldungen mit dem Schweregrad eines “Fehlers” werden in Rot ausgezeichnet
*Erklärung zu "beliebig" und "keine Beschränkung": In der Firmware des Timberwolf Servers sind keine künstlichen Limits implementiert, die über sich technisch ergebende Grenzen hinaus gehen.
Technischen Grenzen sind z.B. die verfügbaren Bandbreiten der Bussysteme und Schnittstellen, die Fähigkeiten der angesprochenen Endgeräte, der Adressumfang und die Datentransportfähigkeiten der jeweiligen Protokolle, die Kompatibilität der jeweiligen Datentypen, die erlaubten Datenflussrichtungen sowie die sich aus der gesamten Konfiguration des Timberwolf Servers ergebende Systemlast.
Der Verzicht auf vorgegebene Beschränkungen bedeutet nicht, dass jede denkbare Konfiguration in jeder Kombination und in jedem Umfang möglich ist. Wir glauben an die Mündigkeit und das Verständnis der Nutzer und erlauben durch weitgehenden Verzicht auf vorgegebene Limits, die verfügbaren Systemressourcen des Timberwolf Servers und der angeschlossenen Geräte im selbst gewählten Umfang zu nutzen.