Services: API registration (Connect 2024)

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:

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

Spaces within the individual parts must be replaces by underscores (_), the parts of the name are separated by two underscores (__). The corresponding file must be stored in the "OpenAPI" directory using the Administration → Storage Management page. The custom property "x-event" is currently used to specify webhooks. This procedure will probably be adapted within the next Connect Server releases.

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/ and myexample/page1 would be combined to https://www.example.com/examples/test/myexample/page1, and the URIs https://www.example.com/examples/test and myexample/page1 would be combined to https://www.example.com/examples/myexample/page1. Removing the "Strict" option causes the combination to return the result https://www.example.com/examples/test/myexample/page1 in both cases.

The option "Path variables are not encoded by default" causes variables within the path not to be encoded for URIs. Thus, the URI template https://www.example.com/examples/{path} and the value "myexample/page1" will not result in the URI https://www.example.com/examples/myexample%2Fpage1 but the URI https://www.example.com/examples/myexample/page1. The 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 require this feature by design. 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 "Configuration Schema", defines a JSON schema that describes the configuration fields required when creating a connection. In the example above, the Conigma CCM API requires a logon to an SAP system. Therefore, 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 these fields are mandatory. A corresponding JSON schema for the configuration could look like this:

More information about JSON Schema in general can be found at the following link:

For passwords, it is important that the description in the associated "title" attribute contains the keyword "Password". This causes the corresponding input field in the UI to be rendered as a password field. When saving the configuration, the 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 Connections: Managing connections (Connect 2024).

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

As a client, this example requires an HTTP client (class Http.Client.HttpClient). 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. For HTTP requests of type POST, PUT and DELETE, SAP requires a CSRF token. The corresponding functionality is included as a handler (class Http.Client.Handlers.HttpCsrfTokenHandler). Since the service requires authentication using Basic Authentication, an additional handler (class Http.Client.Handlers.HttpBasicAuthenticationHandler) 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) which 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.

An HTTP server (class Http.Server.HttpServer) is required as a server for processing the webhooks. Additional HTTP handlers are not required in this example.

In rare cases, the values for automatically generated query parameters should be accepted without being encoded for use in URIs. This behavior can be enforced by adding the following JSON to the service definition: