Initial settings

The following settings should be adjusted in advance if APIs are called from or made available:

• Adjust OpenAPI/Swagger URL in configuration file ./etc/startup.xml of the inner system:
  

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

  In order for customers and partners to be able to access the OpenAPI overview, the URL under which the Integration Server can be accessed from outside should be defined here.
  If a DMZ server is in use, the URL of the DMZ must be used (please retain the /dw/request).

• Optional: Activate HTTPS.

• Optional: Force HTTPS (set parameter forceSSL to true in ./etc/startup.xml).

Authentication

Most REST APIs are not publicly accessible and require prior authentication so that the data can be accessed.

It is generally recommended to use channels for authentication, as these can be managed centrally and used for multiple profiles.

As soon as a channel has been set in phase 1/3/6, the header Authorization is automatically added to the request.

Various authentication options can be configured in the HTTP channel:

• Basic auth/Digest auth

• OAuth2

• OAuth1

• Generic Bearer Token

These are active in the following order: Basic > OAuth2 > Generic Bearer Token.

If the validity of the OAuth2/Generic Bearer Token has expired, the channel is executed beforehand during a profile run and the token is updated in the background.

In specific cases, the Generic Bearer Token may not be sufficient. A separate predecessor profile with its own logic in phase 3 can be used for authentication.

Setting up HTTP headers in the channel (profile as client)

Channel-related HTTP headers can be stored via Channels → Additional IDs. These are defined using the SYS_HTTP_ prefix and are automatically sent as soon as the channel has been assigned to a profile.

The additional ID must first be created in the main menu 'Additional IDs'. The values can then be added to the HTTP channel in the Additional IDs tab by right-clicking. In the example shown for headers Accept and User-Agent HTTP.

REST API request (profile as client)

The following options are available if a profile is to act as a client, i.e. retrieve data from other web services:

• Phase 1: Time-driven Input Agent "HTTP".
  The response of the request is available as the source structure in phase 3 or via system variables.

• Phase 3: http or http json-lookup function.
  The response is written to the specified map of the function.

• Phase 6: Response "HTTP".
  The response can be viewed in the log or in the menu 'Server log' → 'internal' log (Base64-encoded). Alternatively, a subsequent profile can be specified for the evaluation (see example profile Forward response to a subsequent profile).

REST API endpoint (profile as server)

If a profile should act as a REST API/web service, the following option is available:

• Phase 1: Event-based HTTP Input Agent.

Error handling

Error message when calling the profile:

• Problems with mandatory query parameters, the HTTP method (GET/POST) is not correct, URL is not correct.

A status code 404 in the OpenAPI/Swagger overview can have the following causes:

• The profile is not active.

• The port/IP to the endpoint is not correct.

• Internal and external endpoint URLs are different (e.g. if you have a DMZ server).

• There is a second web server (can be checked in the Admin Console).

• Routing, proxy or firewall block access.