Last Update: 30.08.2024

Initiale Einstellungen

Folgende Einstellungen sollten vorab angepasst werden, wenn APIs aufgerufen oder zur Verfügung gestellt werden:

OpenAPI/Swagger-URL in der Konfigurationsdatei ./etc/startup.xml des inneren Systems anpassen:

<Set name="webServiceUrl">https://mycompany.com/dw/Request</Set>

Damit beispielsweise Kunden und Partner auf die OpenAPI-Übersicht zugreifen können, sollte dort die URL hinterlegt werden, unter der der Integration Server von außen erreichbar ist.
Ist ein DMZ-Server im Einsatz, muss die URL von diesem verwendet werden (das /dw/Request bitte beibehalten).
Optional: HTTPS aktivieren.
Optional: HTTPS forcieren (in der ./etc/startup.xml den Parameter forceSSL auf true setzen).

Authentifizierung

Die meisten REST APIs sind nicht öffentlich zugänglich und benötigen vorab eine Authentifizierung, damit auf die Daten zugegriffen werden kann.

Grundsätzlich wird empfohlen, Kanäle für die Authentifizierung zu verwenden, da diese zentral verwaltet und für mehrere Profile verwendet werden können.

Sobald ein Kanal in Phase 1/3/6 hinterlegt wurde, wird dem Request der Header Authorization automatisch hinzugefügt.

Im HTTP-Kanal lassen sich verschiedene Authentifizierungs-Möglichkeiten hinterlegen:

Basic Auth/Digest Auth
OAuth2
OAuth1
Generic Bearer Token

Diese sind in folgender Reihenfolge aktiv: Basic > OAuth2 > Generic Bearer Token.

Ist die Gültigkeit des Tokens bei OAuth2/Generic Bearer Token abgelaufen, wird bei einem Profil-Lauf zuvor der Kanal ausgeführt und der Token aktualisiert.

Bei speziellen Ausnahmefällen kann auch der Generic Bearer Token nicht ausreichend sein. Dann kann ein separates Vor-Profil für die Authentifizierung genutzt werden.

Eigene HTTP-Header im Kanal hinterlegen (Profil als Client)

Über Partnerkanäle→Zusatzkennungen lassen sich kanalbezogene HTTP Header hinterlegen. Diese werden über den Präfix SYS_HTTP_ definiert und automatisch mitgesendet, sobald der Kanal einem Profil zugewiesen wurde.

Die Zusatzkennung muss zuvor im Hauptmenü angelegt werden. Anschließend können die Werte im HTTP-Kanal im Tab Zusatzkennung mit Rechtsklick hinzugefügt werden. Im Beispiel gezeigt für die HTTP-Header Accept und User-Agent.

images/download/attachments/169631174/image-2024-6-24_10-54-58-version-1-modificationdate-1719219298292-api-v2.png

REST API Request (Profil als Client)

Folgende Möglichkeiten gibt es, wenn ein Profil als Client agieren soll, also Daten von anderen Webservices abholt:

Phase 1: Zeitgesteuerter HTTP-Eingangsagent.
Die Response steht als Quellstruktur in Phase 3 bzw. über System-Variablen zur Verfügung.
Phase 3: http bzw. http json-lookup Funktion.
Die Response wird in die angegebene Map der Funktion geschrieben.
Phase 6: Antwortweg HTTP.
Die Response kann im Log bzw. Serverlog → "internal"-Log eingesehen werden (Base64-kodiert). Alternativ kann ein Folge-Profil für die Auswertung angegeben werden (siehe Beispiel Response weiterleiten an Folge-Profil).

Beispiele

Die Beispiel-Profile wurden mit https://petstore.swagger.io oder anderen öffentlich zugänglichen APIs umgesetzt. Sie erfordern Zugriff auf die entsprechenden Seiten, sowie eine Version >= 4.6.11.

Hinweis: In vielen Beispielen wurden Infos zum Mapping und Funktionen in den Knoten-/Feldbeschreibungen hinterlegt! Die Beschreibung kann in Phase 3 über den Button aktiviert werden!

Beschreibung	Hinweise/Sonstiges	Beispiel-Profil (Download)
GET-Request.	Einfacher GET Request in Phase 1. Speichert die Response in Phase 6 als Backup.	Profile-GET_request.pak
POST-Request.	Einfacher POST Request mit Body-Daten in Phase 1. Speichert die Response in Phase 6 als Backup.	Profile-POST_request.pak
GET-Request mit Metadaten.	Einfacher GET Request in Phase 1. Auswerten von Metadaten anhand von System-Variablen wie HTTP Header in Phase 3. Speichert die Response als Backup.	Profile-GET_request_fetch_metadata_phase3.pak
Response weiterleiten an Folge-Profil.	Profil: GET Request in Phase 6 und leitet Response mittels Message an Profil 2. Profil: Nimmt die Response aus Profil 1 entgegen. Speichert die Response als Backup.	Profile-1_forward_response_GET_request_phase6.pak Profile-2_forward_response_receiver_profile.pak
MSG_CALL_-Variablen in Profil-Kette verwenden.	Ein variables Datum wird per Vor-Profil übergeben. Profil: Bereitet ein aktuelles Datum auf und übergibt es mittels MSG_CALL_-Variable an das zweite Profil. Profil: GET Request in Phase 1 mit dem zuvor erzeugtem Datum. Speichern der Response in Phase 6 als Backup. Hinweis: Wird das aktuelle Datum benötigt, kann man mit Formatvorlagen arbeiten, z. B.: <yyy><MM><dd>	Profile-1_forward_variables_create_specific_date_and_data.pak Profile-2_forward_variables_POST_request_phase1.pak
API Paging/Pagination	API Paging mit zwei verschiedenen Methoden.	Siehe Tutorial.
"Last-run"-Variable verwenden für nächsten Profil-Lauf.	Es wird die "Last-run"-Variable verwendet, um Datum und Uhrzeit des letzten Profil-Laufs als Query-Parameter zu übergeben.	Profile-GET_request_last_run_variable.pak
Multipart-Request in Phase 6.	Sendet einen Multipart Request in Phase 6 an requestcatcher.com (öffentlicher API Endpunkt, → Vorsicht mit sensiblen Daten!). Hinweis: Bitte validen Dateipfad und Dateinamen hinterlegen!	Profile-send_multipart_in_phase6.pak
Multipart-Request in Phase 3.	Sendet einen Multipart Request in Phase 3 mittels HTTP-Funktion. Hinweis: Bitte validen Dateipfad und Dateinamen hinterlegen! (mit "add to map"-Funktion).	Profile-send_multipart_in_phase3_httpfunction.pak
ODATA-Beispiel.	Beispiel eines GET Request mit ODATA-Standard. Link zur API: https://pragmatiqa.com/xodata/	Profile-OData_GET_request_phase1.pak
GraphQL-Request.	Beispiel eines Requests mittels GraphQL. Da wir noch keine native Unterstützung für GraphQL haben, können Online-Konverter für die Umwandlung von GraphQL in JSON verwendet werden. Beispiel: https://datafetcher.com/graphql-json-body-converter	Wie Standard-GET- und POST-Requests in Phase 1/3/6, mit JSON-Body-Daten aus dem Online-Konverter-Tool.

REST API Endpoint (Profil als Server)

Soll ein Profil als REST API/Webservice fungieren, gibt es folgende Möglichkeit:

Phase 1: Event-gesteuerter HTTP-Eingangsagent.

Beispiele

Hinweis: Die Request-URL bitte entsprechend anpassen: http bzw. https, wenn HTTPS aktiv ist und auf die Custom Ports achten.

Beschreibung	Hinweise/Sonstiges	Beispiel-Profil (Download)
Simpler REST API Endpoint.	Einfaches REST-API-Profil für Tests, ob Daten empfangen werden können bzw. ob der Integration Server erreichbar ist. Request-URL: https://<Integration Server>/dw/Request/receiver_endpoint/nomapping/	Profile-receiver_endpoint_nomapping.pak
Simpler REST API Endpoint, Webservice-Response.	REST-API-Profil übergibt Fixwerte aus Phase 3 zurück an den Client als JSON. Request-URL: https://<Integration Server>/dw/Request/receiver_endpoint/get_address/	Profile-receiver_endpoint_mapping_custom_response.pak
Multipart Requests/Anhänge speichern.	Nimmt Multipart Requests in Phase 1 entgegen und speichert die Infos in der Logübersicht. Beispiel-Request Postman: Request-URL: https://<Integration Server>/dw/Request/receiver_endpoint/multipart_receiver/	Profile-receiver_multipart.pak
Fortgeschrittene HTTP-Fehler-Response.	Auswerten der Path-Variable in Phase 1, Error-Handling mit neuen Funktionen (throw http error) in Phase 3. Rückgabe der Fixwerte an Client. Request-URL: https://<Integration Server>/dw/Request/receiver_endpoint/error_responses/	Profile-error_responses.pak
Binäre Response.	Lokal gespeicherte PDFs zurückgeben. Liest lokal gespeicherte PDF-Dateien ein und gibt sie dem aufrufenden Client als direkten Download zurück. Request-URL: https://<Integration Server>/dw/Request/get_pdf/	Profile-Binary_response_pdf.pak

Error Handling

Fehlermeldung beim Aufrufen des Profils:

Your request could not be processed due to unknown/mismatched parameters

Probleme mit Pflicht-Query-Parametern. Die HTTP-Methode (GET/POST) stimmt nicht, URL ist nicht korrekt.

Ein Statuscode 404 in der OpenAPI/Swagger-Übersicht kann folgende Ursachen haben:

Das Profil ist nicht aktiv.
Port/IP zum Endpunkt ist nicht korrekt angegeben.
Interne und externe Endpunkt-URL sind unterschiedlich (z. B. wenn Sie einen DMZ-Server haben).
Es gibt einen zweiten Webserver (überprüfbar in der Admin-Konsole).
Routing, Proxy oder Firewall blockieren den Zugriff.