Services: Registrierung von APIs (Connect 2024)

Dieser Bereich des Connection Designer dient der Verwaltung von Metadaten externer APIs. Diese können hier registriert (angelegt), bearbeitet oder deregistriert (gelöscht) werden. In den meisten Szenarien werden Sie auf API-Definitionen zurückgreifen, welche zusammen mit dem Connect Server ausgeliefert wurden. In diesem Fall ist keine Änderung an den registrierten APIs erforderlich.

Registrieren einer API (Connect 2022)

Voraussetzungen

Für die Registrierung einer neuen API, wird eine API-Beschreibung im OpenAPI- oder im Swagger-Format benötigt. Nähere Informationen zu OpenAPI finden Sie unter folgendem Link:

Die API-Beschreibung muss im JSON-Format vorliegen, Spezifikationen im YAML-Format können einfach mit Hilfe von Online-Konvertern in das JSON-Format übersetzt werden. Die Benennung der JSON-Datei muss folgender Konvention folgen:

[Name des Herstellers]__[Name des Produkts]__[Version des Produkts bzw. der API].json

Leerzeichen innerhalb der einzelnen Namensbestandteile müssen durch einen Unterstrich (_) ersetzt werden, die Namensbestandteile werden durch einen doppelten Unterstrich (__) getrennt. Die entsprechende Datei muss den Punkt Administration → Speicherverwaltung im Verzeichnis “OpenAPI” abgelegt werden. Zur Spezifikation von Webhooks wird derzeit das Custom-Property “x-event” verwendet. Diese Vorgehendweise wird voraussichtlich im Rahmen der nächsten Connect Server Versionen angepasst.

Vorgehensweise

Navigieren Sie zur Seite Connection Designer → Services und klicken Sie auf die Schaltfläche “Service hinzufügen”. Nun erscheint ein Fester zur Eingabe des Herstellers, des Produktnamens und der Version des Produkts bzw. der API. Geben Sie hier exakt dieselben Informationen ein, die Sie für die Benennung der OpenAPI-Datei verwendet haben und klicken Sie anschließend auf die Schaltfläche “OK”.

Anschließend wird der Editor für die API-Definition angezeigt.

Im oberen Bereich kann im Feld Titel eine Kurzbeschreibung und im Feld Beschreibung eine ausführlichere Beschreibung der API erfasst werden. Beide Felder unterstützen Mehrsprachigkeit, so dass ein Standardwert und Übersetzungen für unterschiedliche Sprachen gepflegt werden können.

Die Felder Name, Hersteller, Produktname und Version können nicht verändert werden, da hierdurch die Referenz auf die entsprechende OpenAPI-Datei zerstört würde.

Im Feld URI Template Optionen können spezielle Optionen für den Umgang mit URI-Templates ausgewählt werden. In der Regel kann hier die Standardauswahl “Strict” beibehalten werden. Deaktivieren Sie diese Aktion nur dann, wenn sämtliche URIs so behandelt werden sollen, wie wenn sie einen abschließenden Schrägstrich besitzen würden. Dies hat Auswirkungen bei der Kombination von Teil URIs. Standardkonform würden die URIs https://www.example.com/examples/test/ und myexample/page1 zu https://www.example.com/examples/test/myexample/page1 kombiniert, die URIs https://www.example.com/examples/test und myexample/page1 zu https://www.example.com/examples/myexample/page1 kombiniert. Das Entfernen der Option “Strict” bewirkt, dass die Kombination in beiden Fällen das Ergebnis https://www.example.com/examples/test/myexample/page1 liefert.

Die Option “Path variables are not encoded by default“ bewirkt, dass Variablen innerhalb des Pfads nicht für URIs codiert werden. Somit wird aus dem URI Template https://www.example.com/examples/{path} und dem Wert “myexample/page1“ nicht die URI https://www.example.com/examples/myexample%2Fpage1 sondern die URI https://www.example.com/examples/myexample/page1. Die Verwendung dieser Option sollte nach Möglichkeit vermieden werden, da hierbei durch entsprechend gesetzte Werte der Variablen auf nicht vorgesehene APIs verwiesen werden kann. Dies ist besonders dann gefährlich, wenn der Dienst einen Verweis auf das Übergeordnete Verzeichnis mit Hilfe von “..” zulässt. Leider sind die APIs einiger Anbieter (z. B. Google) so konzipiert, dass dieses Feature benötigt wird. In diesem Fall kann die API nur durch Aktivierung dieser Option genutzt werden.

Es ist möglich mehrere Optionen zu markieren. Halten Sie hierfür die Strg-Taste gedrückt und selektieren bzw. deselektieren Sie nacheinander die gewünschten Optionen.

Im unteren Bereich des Editors befinden sich drei JSON Editoren. Der oberste mit der Beschriftung “JSON Schema für die Konfiguration“ definiert ein JSON Schema, welches die bei der Anlage einer Verbindung benötigten Konfigurationsfelder beschreibt. Im obigen Beispiel muss eine Anmeldung an ein SAP-System mit Conigma CCM erfolgen. Hierfür wird die Basis URI des entsprechenden Service, der SAP-Mandant, der SAP-Benutzer, das Passwort des SAP-Benutzers sowie die gewünschte Anmeldesprache benötigt. Hierbei sind alle Felder verpflichtend. Ein entsprechendes JSON Schema für die Konfiguration kann z. B. folgendermaßen aussehen:

Nähere Informationen zu JSON Schema allgemein finden Sie unter folgendem Link:

Bei Passwörtern ist es wichtig, dass die Beschreibung im zugehörigen “title”-Attribut das Schlüsselwort “Password” enthält. Somit wird für die Eingabe ein verdecktes Passwortfeld generiert. Bei der Speicherung der Konfiguration kann dies gesamte Konfiguration oder auch Teile davon verschlüsselt werden, so dass z. B. Passwörter nicht im Klartext abgelegt werden. Nähere Informationen hierzu entnehmen Sie den Abschnitt Verbindungen: Verwalten von Verbindungsinformationen (Connect 2024).

Die folgenden beiden JSON Editoren definieren den für die API bereitgestellten Client bzw. den für die API bereitgestellten Server.

Als Client benötigt dieses Beispiel einen HTTP-Client (Klasse Http.Client.HttpClient). Der HTTP Client benötigt die Basis-URI des Service und bezieht diese mittels der JSON Path Expression $.connection.config.baseUri aus der Konfiguration der Connection. Für HTTP Anforderungen vom Typ POST, PUT und DELETE benötigt SAP ein CSRF-Token. Die entsprechende Funktionalität wird als Handler (Klasse Http.Client.Handlers.HttpCsrfTokenHandler) eingebunden. Da der Service eine Authentifizierung mittels Basic Authentication erfordert muss ein zusätzlicher Handler (Klasse Http.Client.Handlers.HttpBasicAuthenticationHandler) eingebunden werden. Dieser bezieht den Benutzernamen und das Passwort per JSON Path Expression aus der Konfiguration der Connection. Zuletzt wird noch ein Request Update Handler eingebunden (Klasse Http.Client.Handlers.HttpRequestUpdateHandler) welcher bei allen HTTP Anforderungen die Query-Parameter für den SAP-Mandant sowie die Anmeldesprache ergänzt.

Das optionale Attribut “httpPerformanceTestMethodName” spezifiziert den Namen einer Methode aus dem OpenAPI-Dokument, welche für Verbindungs- und Performancetests verwendet werden kann.

Als Server wird ein HTTP-Server (Klasse Http.Server.HttpServer) zur Verarbeitung der Webhooks benötigt. Zusätzliche HTTP-Handler kommen hier in diesem Beispiel nicht zum Einsatz.

In seltenen Fällen ist es gewünscht, dass die Werte für automatisch generierte Query Parameters übernommen werden, ohne dass diese für die Verwendung in URIs codiert werden. Dieses Verhalten lässt sich erzwingen, indem der Service-Definition folgende JSON hinzugefügt wird: