Eine Alternative zum Aufbau eines Webdienstes bietet RESTful (Representational State Transfer) API (Application Programming Interface) oder WebAPI. Die RESTAPI bildet die Architektur für eine einheitliche Schnittstelle zu Systemen oder Programmen, um Daten per HTTP-Request in standardisierter Form zu übertragen oder zu verwenden.

Zustandslose Client/Server-Kommunikation (stets neuer Aufbau, cloudfähig).
Übertragungsformat: JSON (bevorzugt), HTML, Plaintext, u.a.
Protokoll: HTTP mit zulässigen Standard-Methoden: GET, PUT, POST, DELETE.
Cachingfähige Daten.
Unterschiede in Request- und Response-Header in Bezug auf Verbindungsinformationen und Statuscodes.
Header und Parameter bilden wichtige Komponenten in den HTTP-Methoden einer RESTful-API-HTTP-Anforderung:
- Metadaten mit ID-Informationen.
- Autorisierung.
- URI.
- Caching.
- Cookies, usw.

Hinweis: Einen guten Überblick zu dem Thema REST finden Sie beispielsweise bei Microsoft.

Leider gibt es im Gegensatz zu SOAP hier keine Standardisierungsinstanz. Für SOAP haben sich mit der Schnittstellenbeschreibung WSDL verschiedene Ansätze etabliert, z. B. Swagger (früher OpenAPI) oder RAML.

RESTful API

Sie benötigen in der Regel ein simples Profil, dass die Anforderung an die Schnittstelle umsetzt.

Angenommen Sie möchten Daten über die API entgegennehmen, so reicht es aus im Eingangsagenten die Methode POST einzustellen und die Checkbox "Als REST-Schnittstelle behandeln" zu aktivieren.

images/download/attachments/137306111/methoden_soap-version-1-modificationdate-1686898154819-api-v2.png

Sie möchten zur Verwendung einer RESTful API HTTP-Methoden verwenden, um beispielsweise einen Kundenstammsatz um einen neuen Kunden (PUT) zu erweitern, die Anzeige der Kundendaten (GET/POST) zu erhalten, die Stammdatensätze zu aktualisieren (PATCH) oder einen Stammdatensatz zu löschen (DELETE). Im ersten Fall steht noch kein Datensatz zur Verfügung, aber in den anderen Fällen kann ein konkretes Objekt, z. B. mit Hilfe eines Parameters für eine variable Kundennummer, direkt in der URL mitgegeben und via API abgerufen werden.

GET https://<Server>/dw/Request/showCustomer/<KUNDENNUMMER>

alternativ auch mit Query-Parameter

GET https://<Server>/dw/Request/showCustomer/?USERID=4711

In diesem Fall empfehlen wir in dem neu erstellten REST-Profil dem "URL Adressen Präfix" den Wert showCustomer zu geben. Setzen Sie nun den HTTP-Aufruf im Browser ab, so führt dieser zum Erfolg. Über die Systemvariable MSG_CALL_HTTP_PATH_DATA haben Sie in Phase 3 die Möglichkeit die zusätzlichen Teile des Requests zu lesen und z. B. über eine Datenbankabfrage gegen den Wert 4711 zu starten. Das Ergebnis können Sie dem Client dann als JSON zurück liefern.

Hinweis: Ab und an erwarten REST-APIs besondere Parameter wie beispielsweise den Accept-Header, mit dem dem Server mitgeteilt wird, welche Ausgaben der Client vom Server akzeptiert. Hier tun Sie gut daran, den Wert "*/*" zu verwenden.

Swagger und RAML

Anders als bei SOAP mit WSDL gibt es zwar keine einheitliche Schnittstellenbeschreibung, allerdings haben sich hier zwei Formate heraus kristallisiert.

Für RAML können Sie ab der Version 4.1 eine Schnittstellenbeschreibung über den Profilexport generieren.

images/download/attachments/137306111/export_profil-version-1-modificationdate-1686898154832-api-v2.png

Solch eine Schnittstellendatei dient dazu eine Mapping-Struktur zu generieren. Innerhalb der Basis-Daten oder in Phase 3 lässt sich ein "Struktur-Import" ausführen.

images/download/attachments/137306111/basisdaten_import-version-1-modificationdate-1686898154841-api-v2.png

Verbreitet ist das Format Swagger (mittlerweile bekannt unter OpenAPI). Ab der Version 4.1 kann eine Swagger-Datei zur Erzeugung von Quell- bzw. Zielstrukturen verwendet werden. Laden Sie dazu über das entsprechende Menü der Quell- oder Zielstruktur und die Funktion "Datei analysieren" die JSON-Datei herunter. Bei erfolgreicher Analyse bietet Ihnen der Dialog die Möglichkeit den Swagger-Import anzuwenden.

Daraufhin werden die in Swagger definierten Strukturen als Teil-Strukturen angelegt und können daraufhin manuell angepasst werden. Für weitere Hinweise beachten Sie bitte auch die Dokumentation.