Technical Process als OpenAPI-ReST-Service bereitstellen

Voraussetzung:

Sie verfügen über ein ESB Project mit mindestens einem Technical Process.

Um im Webservice Configuration Editor einen Technical Process als Operation eines OpenAPI-ReST-Webservice bereitzustellen, gehen Sie wie folgt vor:

Geben Sie die gewünschten Daten auf der Registerkarte OpenAPI ein.

Name, Title und Version sind obligatorische Felder, in die Sie einen Wert eingeben müssen. Wenn das API eine Methodenbeschreibung anzeigen soll, geben Sie in das Feld Description eine Beschreibung ein.
Legen Sie in der Baumstruktur bei Bedarf einen neuen Knoten an (entspricht einem URL-Part des Webservices). Weitere Informationen hierzu finden Sie unter Webservice-Konfiguration grafisch bearbeiten.
Legen Sie für den gewünschten Knoten (vom Typ Constant, Variable oder Remainder) über Add HTTP ReST Service einen neuen Service vom Typ HTTP ReST an. Passen Sie ggf. die (Sicherheits-)Eigenschaften an.

Bevor Sie einen HTTP-ReST-Service anlegen, müssen Sie auf der Registerkarte General den Wert Provide OpenAPI auf true setzen und das Kontrollkästchen Inherit from parent node deaktivieren. Damit geben Sie an, dass Sie OpenAPI im HTTP-ReST-Service verwenden.
Legen Sie für den HTTP-ReST-Service über das Kontextmenü Add HTTP ReST Operation eine neue Operation an, oder wählen Sie in der Tabelle Operations einen bestehenden Eintrag aus, der überschrieben werden soll.

Sie können jeweils einmal pro Service eine Operation GET, POST, PUT, DELETE vergeben oder einen frei wählbaren Operationsnamen eingeben. Bei den Operationsnamen wird zwischen Groß-/Kleinschreibung unterschieden.
Ziehen Sie einen Prozess aus der Ansicht Projects per Drag&Drop auf die gewünschte Operation, um den Prozesspfad zuzuordnen.
Legen Sie über die Dropdown-Liste Output Mode den Output-Modus HTTP-Content fest, um die Prozess-Response anzuzeigen.
Wenn der ReST-Service Query-Parameter erfordert, können Sie diese Parameter anlegen. Dazu klicken Sie in der Registerkarte OpenAPI im Gruppenfeld Query Parameter auf die Schaltfläche Add. Beim Hinzufügen neuer Parameter müssen Sie einen Namen für den Parameter und weitere Optionen wie Type, Array und Required angeben.
Über die Registerkarten Request und Response können Sie einen benutzerdefinierten Request und eine benutzerdefinierte Response für die jeweilige Methode anlegen.

Mit einem Datenmodell arbeiten

Sie können Ihren ReST-Service so konfigurieren, dass er Werte in Tabellenform aus einem Datenmodell übernimmt und Werte in Tabellenform ausgibt. Dazu müssen Sie zunächst im X4 Designer ein Data Model Project mit mindestens einer Entity anlegen. Jede Entity muss mindestens ein Feld enthalten. Weitere Informationen hierzu finden Sie unter Mit Data Model Projects arbeiten.

Die Datenübernahme aus einem Data Model Project ist für die Methoden POST, PUT und DELETE möglich.

Request mit Data Model

Um festzulegen, dass die Eingabedaten für einen Technical Process im Tabellenformat vorliegen sollen, führen Sie die folgenden Schritte auf der Registerkarte OpenAPI aus:

Klicken Sie auf der Registerkarte Request auf die Schaltfläche Add, und geben Sie im Feld Content-Type einen Namen ein. Klicken Sie dann in das Feld Data Model, und wählen Sie die Schaltfläche mit den drei Punkten.
Wählen Sie im Dialogfenster Select Entities in der Dropdown-Liste Data Model das gewünschte Data Model Project aus, und aktivieren Sie das Kontrollkästchen für die Tabelle, deren Werte Sie übernehmen möchten. Die Tabelle entspricht der Entity, die Sie im Data Model Project angelegt haben.

Response mit Data Model

Wenn auch die Ausgabedaten eines Prozesses das Format einer Tabelle haben soll, führen Sie die folgenden Schritte auf der Registerkarte OpenAPI aus:

Klicken Sie im Bereich Status Codes auf die Schaltfläche Add, und geben Sie den jeweiligen HTTP-Statuscode an.
Geben Sie eine Beschreibung in das Feld Description ein.
Klicken Sie im Bereich Contents auf Add, um Inhalte zur Response hinzuzufügen.
Klicken Sie im Feld Data Model auf die Schaltfläche mit den drei Punkten.
Wählen Sie im Dialogfenster Select Entities das gewünschte Data Model Project aus, aktivieren Sie das Kontrollkästchen für die gewünschte Tabelle, und klicken Sie auf OK.

Authentifizierung festlegen

Um eine Methode als privat festzulegen, markieren Sie die gewünschte Methode im Webservice Configuration Editor, und gehen Sie wie folgt vor:

Deaktivieren Sie für das Feld Realm das Kontrollkästchen Inherit from parent node.
Geben Sie den gewünschten Wert in das Feld Realm ein, z. B. X4Realm.

ReST-Service testen

Um das konfigurierte OpenAPI im Browser zu öffnen, gehen Sie wie folgt vor:

Rufen Sie die URL http://localhost:8080/X4/httpstarter/ReST/[ESB_CONSTANT_VALUE]/openapi.html auf. Ersetzen Sie [ESB_CONSTANT_VALUE] durch den Namen Ihres Projekts.
Alternativ können Sie mit der rechten Maustaste auf die Methodenoperation klicken und im Kontextmenü Copy OpenAPI URL to Clipboard wählen. Fügen Sie die kopierte URL dann im Browser ein.
Erweitern Sie unter Service den Eintrag für eine Methode, und klicken Sie auf Try it out.

Wenn Ihr ReST-Service Parameter enthält, müssen Sie diese unter Parameter eingeben, bevor Sie auf Execute klicken.

Wenn Ihr ReST-Service ein Data Model Project enthält, befinden sich die Daten im Request-Body. Sie müssen den benötigten Wert eingeben, bevor Sie auf Execute klicken.
Klicken Sie auf Execute.

Das Ergebnis der Operation wird unter Responses angezeigt.

ReST-Service mit Authentifizierung testen

Wenn für einen ReST-Service eine Authentifizierung festgelegt wurde, erkennen Sie das daran, dass die Methode auf der rechten Seite mit einem Schloss-Symbol versehen ist. Wenn Sie die Methode öffnen, auf die Schaltfläche Try it out klicken, ggf. einen Parameter eingeben und auf Execute klicken, wird ein Dialogfenster angezeigt, in dem Sie Ihren Benutzernamen und Ihr Passwort eingeben müssen. Nach Eingabe der Zugangsdaten wird die Methode ausgeführt, und die Response wird angezeigt.