Page Comparison

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

Voraussetzungen

...

This area of the Connection Designer is used to manage metadata of external APIs. These can be registered (created), edited or deregistered (deleted) here. In most scenarios, you will use API definitions that were shipped with the Connect Server. In this case, no change to the registered APIs is required.

Register an API

Requirements

To register a new API, an API description in OpenAPI or Swagger format is required. More information about OpenAPI can be found at the following link:

...

Die API-Beschreibung muss im JSON-Format vorliegen, Spezifikationen im YAML-Format können einfach mit Hilfe von Online-Kovertern 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

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 The API description must be in JSON format, specifications in YAML format can be easily translated to JSON format using online overlays. The naming of the JSON file must follow the following convention:

[name of the manufacturer]__[name of the product]__[version of the product or API].json

The corresponding file must be stored in the Administration → Memory Management item in the "OpenAPI" directory. The custom property "x-event" is currently used to specify webhooks. This procedure will probably be adapted within the next Connect Server versions.

Procedure

Navigate to the page Connection Designer → Services and click the "Add Service" button. Now a window appears for entering the manufacturer, the product name and the version of the product or API. Enter exactly the same information here that you used for naming the OpenAPI file and then click the "OK" button.

...

Then the editor for the API definition is displayed.

In the upper area, a short description of the API can be entered in the Title field and a more detailed description in the Description field. Both fields support multilingualism, so that a default value and translations for different languages can be maintained.

The fields Name, Manufacturer, Product name and Version cannot be changed, because this would destroy the reference to the corresponding OpenAPI file.

In the URI Template Options field, special options for handling URI templates can be selected. Usually the default selection "Strict" can be kept here. Disable this action only if all URIs are to be treated as if they had a trailing slash. This has implications when combining partial URIs. By default, the URIs https://www.example.com/examples/test/ und and myexample/page1 zu would be combined to https://www.example.com/examples/test/myexample/page1 kombiniert, die and the URIs https://www.example.com/examples/test und and myexample/page1 zu would be combined to https://www.example.com/examples/myexample/page1 kombiniert. Das Entfernen der Option “Strict” bewirkt, dass die Kombination in beiden Fällen das Ergebnis . Removing the "Strict" option causes the combination to return the result https://www.example.com/examples/test/myexample/page1 liefertin both cases.

Die Option “Path The 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 default" causes variables within the path not to be encoded for URIs. Thus, the URI template https://www.example.com/examples/{path} und dem Wert “myexample/page1“ nicht die and the value "myexample/page1" will not be used to create the URI https://www.example.com/examples/myexample%2Fpage1 sondern die but the 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 aussehenThe use of this option should be avoided if possible, as this can lead to unintended APIs being referenced by variable values that are set accordingly. This is especially dangerous if the service allows a reference to the parent directory using "..". Unfortunately, the APIs of some providers (e.g. Google) are designed to require this feature. In this case, the API can only be used by enabling this option.

It is possible to select multiple options. To do this, hold down the Ctrl key and select or deselect the desired options one after the other.

In the lower part of the editor there are three JSON editors. The top one, labeled "JSON Schema for configuration", defines a JSON schema that describes the configuration fields required when creating a connection. In the example above, a logon to an SAP system has to be done using Conigma CCM. For this, the base URI of the corresponding service, the SAP client, the SAP user, the password of the SAP user and the desired logon language are required. All fields are mandatory. A corresponding JSON schema for the configuration can look like this, for example:

{
  "type": "object",
  "properties": {
    "baseUri": {
      "type": "string",
      "format": "uri",
      "title": "Base URI of HTTP service of the SAP system"
    },
    "sapClient": {
      "type": "string",
      "pattern": "[0-9]{3}",
      "title": "SAP client"
    },
    "sapUser": {
      "type": "string",
      "title": "SAP user"
    },
    "sapPassword": {
      "type": "string",
      "title": "SAP password"
    },
    "sapLanguage": {
      "type": "string",
      "pattern": "[A-Z0-9]",
      "default": "E",
      "title": "SAP language code"
    }
  },
  "required": [
    "baseUri",
    "sapClient",
    "sapUser",
    "sapPassword",
    "sapLanguage"
  ]
}

Nähere Informationen zu JSON Schema allgemein finden Sie unter folgendem LinkMore information about JSON Schema in general can be found at the following 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 der Verbindungsinformationen.

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 For passwords, it is important that the description in the associated "title" attribute contains the keyword "Password". Thus a hidden password field is generated for the input. When saving the configuration, this entire configuration or parts of it can be encrypted so that, for example, passwords are not stored in plain text. For more information, refer to the section Verbindungen: Verwalten der Verbindungsinformationen.

The following two JSON editors define the client provided for the API and the server provided for the API, respectively.

As a client, this example requires an HTTP client (class Http.Client.HttpClient). Der HTTP Client benötigt die Basis-URI des Service und bezieht diese mittels der JSON Path Expression The HTTP client needs the base URI of the service and gets it from the configuration of the connection using the JSON path expression $.connection.config.baseUri aus der Konfiguration der Connection. Für HTTP Anforderungen vom Typ For HTTP requests of type POST, PUT und and DELETE benötigt , SAP ein requires a CSRF -Token. Die entsprechende Funktionalität wird als Handler (Klasse token. The corresponding functionality is included as a handler (class Http.Client.Handlers.HttpCsrfTokenHandler) eingebunden. Da der Service eine Authentifizierung mittels Basic Authentication erfordert muss ein zusätzlicher Handler (Klasse . Since the service requires authentication using Basic Authentication, an additional handler (class 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 must be included. This handler gets the username and password via JSON path expression from the connection configuration. Finally, a request update handler is included (class 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 kannwhich adds the query parameters for the SAP client and the logon language for all HTTP requests.

The optional attribute "httpPerformanceTestMethodName" specifies the name of a method from the OpenAPI document which can be used for connection and performance tests.

{
  "$class": "Http.Client.HttpClient",
  "$params": {
    "baseUri": "$.connection.config.baseUri",
    "handlers": [
      {
        "$class": "Http.Client.Handlers.HttpCsrfTokenHandler",
        "$params": {
          "tokenFetchMethodName": "ping",
          "headerName": "x-csrf-token",
          "renewValue": "fetch",
          "autoRenewOnGetRequest": true
        }
      },
      {
        "$class": "Http.Client.Handlers.HttpBasicAuthenticationHandler",
        "$params": {
          "user": "$.connection.config.sapUser",
          "password": "$.connection.config.sapPassword"
        }
      },
      {
        "$class": "Http.Client.Handlers.HttpRequestUpdateHandler",
        "$params": {
          "defaultQueryParameters": [
            {
              "key": "sap-client",
              "value": "$.connection.config.sapClient"
            },
            {
              "key": "langu",
              "value": "$.connection.config.sapLanguage"
            }
          ]
        }
      }
    ],
    "httpPerformanceTestMethodName": "ping"
  }
}

Als Server wird ein HTTP-Server (Klasse An HTTP server (class Http.Server.HttpServer) zur Verarbeitung der Webhooks benötigt. Zusätzliche HTTP-Handler kommen hier in diesem Beispiel nicht zum Einsatzis required as a server for processing the webhooks. Additional HTTP handlers are not used here in this example.

{
  "$class": "Http.Server.HttpServer",
  "$params": {
    "handlers": []
  }
}