Beispiele zur allgemeinen REST API Verarbeitung

REST (Representational State Transfer) API Web Services sind mittlerweile in aller Munde. Dabei ist REST lediglich eine Architektur für die Entwicklung von Webanwendungen und Schnittstellen, allgemein als APIs bekannt.

In diesem Tutorial wird beschrieben wie mit dem FlowHeater REST API Adapter REST Web Services aufgerufen bzw. abgerufen werden können.

Was sind REST API Web Services?

REST ist eine Softwarearchitektur für die Kommunikation zwischen Systemen über das HTTP-Protokoll eines Webservers. REST-basierte Webservices ermöglichen es, Daten zwischen Client und Server auszutauschen, typischerweise in Form von JSON oder XML, es gehen aber auch andere Formate wie CSV oder einfache Text Dateien.

REST API Web Services werden über die http Methoden GET, POST, PUT, DELETE und PATCH aufgerufen und/oder über Header oder aber GET-Parameter gesteuert. Über diese http Methoden können z.B. aktuelle Messwerte abgerufen, Artikel in einem Webshop aktualisiert oder aber Fremdsysteme eingebunden bzw. angebunden werden. Wie das mit dem FlowHeater REST API Adapter gemacht wird, erfahren Sie weiter unten.

Allgemeine Infos zur REST API Verarbeitung mit dem FlowHeater

Der FlowHeater REST API Adapter wurde so konzipiert, dass damit allgemeine REST API Web Services aufgerufen werden können. Die Verwendung im FlowHeater erfordert jedoch, dass Sie die Konzepte der FlowHeater Verarbeitung verstanden haben. Falls Sie gerade dabei sind sich einzuarbeiten sind diese Beispiele eher schlecht dazu geeignet. Hier empfehlen wir die einfacheren Hello World Beispiele.

Die folgende Beschreibung bezieht sich auf die im Download ZIP Archiv vorhandenen Beispiele. Diese können im FlowHeater Designer über „Menü->Bespiele->REST API Adapter->Allgemeine REST-Verarbeitung“ aufgerufen werden. Hinter diesen Beispielen befindet sich ein kompletter REST Web Service, worüber Sie bedenkenlos testen können. Artikel, die Sie hochladen oder aber aktualisieren, bleiben einen Tag lang verfügbar, danach müssen diese erneut angelegt werden.

Fangen wir an, viel Spaß beim ausprobieren 😊

Die Anmeldung, Beispiel 01_BasicAuth.fhd

REST API Adapter - http basic authJe nachdem welche Art der Anmeldung der REST Web Service anbietet müssen Sie hier unterschiedlich vorgehen. Hier mal ein Beispiel wie über „http Basic Auth“ ein API-Token abgerufen werden kann, der dann für alle nachfolgende Anfragen (Requests) verwendet wird.

Für eine http BASIC Authentifizierung muss dem REST Web Service eine http Header Variable „Authorization“ mitgeschickt werden. Der Inhalt ist Base64 Encoded und hat folgenden Aufbau

     Benutzername:Passwort

Hinweis: In dem Verzeichnis befindet sich ein weiteres Beispiel „00_BasicAuth-Base64-String-generieren.fhd“ worüber Sie den Benutzer und das Passwort in den gewünschten Base64 String umwandeln können. Diesen Wert müssen Sie nun im REST API Adapter über ein Feld mit dem Namen „Authorization“ als Feldtyp „RequestHeater“ anlegen und mit dem Inhalt

     Basic [Base64 encoded Benutzername:Passwort]

siehe Bild rechts. So wird diese Feld als http Header Variable „Authorization“ an den REST Web Service mit dem Inhalt aus dem „Standardwert“ geschickt.

Wenn wir das ausführen oder testen liefert der REST Web Service ein JSON wie folgt zurück.

     {"Token":"400941dd-4f2b-4129-beba-916de14ef764","ExpiresIn":600}

Jetzt könnten wir das mit dem JSON Adapter auslesen und weiterverberarbeiten. Ist aber bei so einem einfachen JSON Content etwas zu viel Overhead, einfacher geht es mit dem SubString Heater. Hier gehen wir über die erweiterten Optionen und extrahieren den ersten Wert zwischen dem Vorkommen von "Token":" bis zum nächsten ",". So haben wird nur den API-Token extrahiert, den wir für die weiteren REST API http Requests benötigen. Dazu setzen wir über den Set Parameter Heater einen FlowHeater Parameter „Token“, den wir in dann in folgenden Verarbeitungsschritten verwenden können.

Der Parameter „ExpireIn“ interessiert uns hier nicht, der sagt nur aus, dass dieser API-Token max. 600 Sekunden (=10 Minuten) gültig ist.

Andere Arten der Anmeldung

Je nachdem wie der REST Web Service konzipiert ist, kommen andere Arten der Anmeldung zum Zuge. Manche REST Web Service verwenden einen langen statischen API-Token, einen „Bearer" bzw. einen JWT (JSON Web Token) Token oder aber was ganz anderes. Das Vorgehen ist aber immer ähnlich und muss nur etwas abgewandelt werden. Der Einfachheit geschuldet verwenden wir hier bei diesen Beispielen weiterhin die „http Basic Auth“ Authentifizierung.

Die Anmeldung, die wir eben durchgeführt haben, verwenden wir nun in den folgenden Beispielen immer wieder als ersten Verarbeitungsschritt, darauf gehen wir nicht weiter ein.

Artikel anlegen, Beispiel 02-UploadArticlesByList.fhd

Der bereitgestellte REST Web Service bietet eine Funktion „UploadArticlesByList“ per HTTP POST an, um Artikel anzulegen oder aber anhand der Artikelnummer zu aktualisieren. Als Content wird eine JSON-Liste von 1-n Elementen wie folgt erwartet.

REST API WebService - Interne JSON VerarbeitungWenn Sie anfangen, sind noch keine Artikel in der zur Verfügung gestellten Datenbank vorhanden. Also erzeugen wir uns mit dem TestData Adapter erstmal 1000 Test-Artikel.

Hinweis: Es werden max. 10.000 Artikel unterstützt. Vorhandene Artikel werden nach spätestens 12 Stunden automatisch gelöscht!

Die benötigte JSON-Struktur erzeugen wir auf der WRITE Seite mit dem JSON Adapter. Da wir die JSON-Datei nicht physisch auf der Festplatte benötigen setzen wir hier die Option „Interne Verarbeitung aktivieren“, siehe Bild rechts.

Im dritten Verarbeitungsschritt müssen wir nun diese eben erzeugte JSON-Artikelliste an den REST Web Service schicken. Dazu geben wir auf der READ Seite im JSON Adapter an dass wir keine physische JSON-Datei einlesen möchten, sondern die im 2 Verarbeitungsschritt erzeugte Struktur. Dazu wählen wir unter „Daten von vorheriger Ausführung lesen“ den zweiten Verarbeitungsschritt und den JSON WRITE Adapter aus.

REST API WebService - JSON Daten lesenDamit der JSON Adapter nun die gesamte JSON-Struktur auf einmal liefert müssen wir hier noch die Option „Gesamten Dateninhalt auf einmal zurückgeben“ aktivieren, siehe Bild rechts.

So wird nur ein Feld „Content“ zur Verfügung gestellt, welches wir mit dem REST API Adapter auf der WRITE Seite verbinden können.

Jetzt müssen wir dem REST API Adapter noch mitteilen wie er dieses Feld interpretieren soll. In dem Fall soll der JSON Inhalt im „HTTP Request Content“ übermittelt werden. Dazu wählen wird für den Feldtyp „RequestContent“ aus. Weiterhin benötigen wir noch ein „HTTP HEADER“ Feld „Authorization“ worüber der im ersten Verarbeitungsschritt erhaltene Bearer Token übermittelt werden kann. Damit das funktioniert, müssen wir für das Feld den Feldtyp „RequestHeader“ auswählen. Als Standardwert verwenden wir hier „Bearer $Token$“. Der FlowHeater Parameter „Token“ wurde ja im ersten Verarbeitungsschritt mit der Anmeldung gesetzt, dieser wird hier automatisch mit dem aktuellen Wert ersetzt.

REST API WebService - Response lesenDer letzte Verarbeitungsschritt wäre nicht notwendig, hier wird lediglich der Status des REST Web Service Aufrufes in eine InMemory Adapter Tabelle geschrieben, um eine evtl. Fehleranalyse durchführen zu können. Um das zu tun, muss hier auf der READ Seite unter URL der REST API Adapter aus dem Verarbeitungsschritt drei ausgewählt werden, siehe Bild rechts.

Einzelnen Artikel abrufen, 03-GetArticleByNr.fhd

Wird demnächst vervollständigt. Aktueller Stand vom 11.10.2025.