Requests über die integrierte Swagger UI senden
Die REST-Schnittstelle des Entry-Programms zur Entgegennahme von Anfragen an die generierte Anwendung ist standardmäßig unter Port 9997 erreichbar. Das Programm entält eine HTML-Oberfläche in Form einer Swagger UI, die Sie verwenden können, um Anfragen an die Anwendung zu senden. Im Folgenden wird schrittweise beschrieben, wie Sie dabei vorgehen können.
Schritt 1: Die Swagger UI der generierten Anwendung aufrufen
Die Swagger UI kann lokal mit der folgenden URL im Web-Browser aufgerufen werden:
Folgende Abbildung zeigt die Swagger UI der Beispielanwendung im Ausgangszustand.
Schritt 2: Die Detailansicht der POST-Operation für /requests öffnen
Generell kann eine Swagger UI unterschiedliche REST-Operationen für diverse Ressourcen zur Verfügung stellen. Im vorliegenden Fall ist nur die POST-Operation zum Anlegen von Requests verfügbar.
Klicken Sie auf die grün hinterlegte Zeile mit der Beschriftung POST /requests, um die Detailansicht der POST-Operation zu öffnen, die in der folgenden Abbildung dargsestellt ist.
Oben, im Bereich Request body werden unter der Überschrift Example Value die JSON-Daten eines möglichen Requests angezeigt. Dabei handelt es sich um formal zulässige Werte, die aus der Spezifkation der REST API hergeleitet werden. Der für input angegebene Eingabstring wird bspw. zufällig auf Basis der zulässigen Werte erzeugt. Es muss sich also nicht um eine sinnvolle Eingabe handeln, in dem Sinne, dass sich der DEA nach der Verarbeitung in einem akzeptierenden Endzustand befindet.
Unten, im Bereich Responses wird unter der Überschrift Example Value ein Beispiel für ein mögliches Ergebnis angezeigt. Auch hier mit rein formal möglichen Werten auf Basis der Spezifikation der REST API.
Um konkrete Daten für einen Request angeben zu können, klicken Sie oben rechts auf den Button mit der Beschriftung Try it out.
Daraufhin wird der Bereich mit dem JSON-Beispiel durch ein mehrzeiliges Textfeld ersetzt, in das ein Request im JSON-Format eingegeben werden kann.
Schritt 3: Einen Request im JSON-Format angeben und senden
Der Beispiel-Request für den Kauf eines Getränks
Der Wert SPR für das Element input im folgenden JSON-Request entspricht den Eingabesymbolen für den DEA, auf dem die Beispielanwendung basiert, um einen einzelnen Getränkekauf durchzuführen. (Ein Zustandsdiagramm und die Definition des DEA für den Getränkeautomaten finden Sie im Abschnitt Ein Getränkeautomat als Beispiel.)
{
"description": "Test-Request 1: Selection, Payment, Removal.",
"input": "SPR"
}-
S für Selection (Getränkewahl)
-
P für Payment (Zahlung)
-
R für Removal (Getränkeentnahme)
Nachdem die JSON-Daten im Textfeld Request body eingegeben wurden, kann der Request durch einen Klick auf den blauen Button Execute gesendet werden, wie in der folgenden Abbildung dargestellt.
Schritt 4: Das Ergebnis des Requests interpretieren
In Folge des Requests werden in der Swagger UI im Bereich Responses diverse Informationen ausgegeben. Die folgende Abbildung zeigt die Ergebnisse für den in Schritt 3 beschriebenen Request.
-
Curl: Hier werden die Parameter angezeigt, die einen ensprechenden Request bei Verwendung von curl auslösen würden. [2]
-
Request URL: Die URL, an die der REST-Request tatsächlich gesendet wurde.
-
Code: Der HTTP Status-Code der Response. Hier 200 für die erfolgreiche Verarbeitung.
-
Response body: Die Nutzlast der Response, sozusagen das eigentliche, anwendungspezifische Ergebnis.
-
Response headers: Die HTTP Header der Response.
Die Daten aus dem Response body als Verarbeitungsinstanz
Im Rahmen der Annahme eines Requests erzeugt das Entry-Programm einen Verarbeitungsinstanz-Datensatz, der die Daten des Requests, den Zeitpunkt der Erzeugung und eine ID enthält. Durch die ID sind Nachrichten, Ereignisse und weitere Datensätze, die im Verlauf der Verarbeitung erzeugt werden, miteinander verknüpft.
Der Datensatz wird in der Datenbank der Anwendung dauerhaft gespeichert und unmittelbar als Ergebnis des POST-Requests an den Aufrufer geliefert.
{
"processingInstanceId": "2d47caed-f271-4ffe-ad76-33d67d7ca3ec", (1)
"creationTime": "2024-08-18T18:24:38.984104390Z", (2)
"input": "SPR", (3)
"description": "Test-Request 1: Selection, Payment, Removal." (4)
}-
Die automatisch erzeugte ID des Verarbeitungsdatensatzes.
-
Der Zeitstempel der Erzeugung.
-
Der mit dem Request übergebene Eingabestring.
-
Die mit dem Request übergebene Beschreibung.