RestApi configuration

ServiceId

ServiceId is a unique logical identifier of a service, used in scripts, script tasks and the data model to refer to a specific REST endpoint. It is not a direct URL, but alias, which is mapped to the actual service address based on the platform configuration.

This way of using services provides flexibility in specifying addresses across environments and administrators can easily change the address in one of the environments. During migrations it is very important that after updating a serviceId or adding a new service this information appears both in the documentation and in configuration tickets.

Configuration

For security reasons, references to external services must be specified in the configuration (serviceId).

The configuration is loaded and processed once at platform startup. This means that additional changes to references will require restarting the application (webforms-rest).

The configuration is read from 2 sources simultaneously (provided properties and an external XML file). Both sources are optional and do not block the application from starting. If a name conflict occurs for serviceId, the last one loaded from the list will be taken into account (reading order from top to bottom).

It is possible to use a reference from the definition of a specific serviceId in another. To use this option, you should define the first serviceId, and then in the reference for the second provide the name of the first serviceId. For example:

scriptservice:
    api:
        - serviceId: "firstServiceId"
          url: "https://my.reference"    # reference: https://my.reference
        - serviceId: "secondServiceId"
          url: "firstServiceId/endpoint"   # reference: https://my.reference/endpoint
          authorization:
            type: basic
            encodedCredentials: cGFzc3dvcmQ=

Using another reference to define a new configuration works correctly only up to 1 nesting (dependencies: A → B).

This means that we cannot have service A's configuration dependent on B, which in turn would be dependent on C (dependencies: A → B → C).

XML configuration

For scripts and script validators:

A file named "script-service-api.xml" should be located in /etc/eximee/webforms/script-code-config.

For script handlers:

A file named "script-handler-api.xml" should be located in /etc/eximee/webforms/script-handler-config.

The file must be manually modified by administrators

File structure:

<?xml version="1.0" encoding="UTF-8" ?>
<scriptservice>
    <api serviceId="myServiceId"
         url="http://my.reference"
         description="Description for hints in Eximee Designer">
        <authorization type="basic">
            <encodedCredentials>cGFzc3dvcmQ=</encodedCredentials>
        </authorization>
    </api>
    <api serviceId="nbp"
         url="http://api.nbp.pl/api"
         description="Reference to the API provided by NBP" />
    <api serviceId="nbpExchange"
         url="nbp/exchangerates"
         description="Reference to NBP API regarding exchange rates" />
</scriptservice>

Configuration after loading:

{
    "nbpExchange": {
        "url": "http://api.nbp.pl/api/exchangerates",
        "description": "Reference to NBP API regarding exchange rates"
    },
    "myServiceId": {
        "url": "http://my.reference",
        "description": "Description for hints in Eximee Designer"
    },
    "nbp": {
        "url": "http://api.nbp.pl/api",
        "description": "Reference to the API provided by NBP"
    }
}

Authentication

Basic

It is possible to define "Basic" authentication per service. Configuration is done in the same file that defines the service references. An example is shown above (note the "authorization" section). Defining the "Authorization" header from the script service level (so-called "hardcode") will generate a warning in the logs. If an authentication method is provided in the service definition (in the file), it has priority and will replace the "Authorization" header that is embedded in the script service file.

The value in the tag encodedCredentials we define by base64-encoding the value

login:password

For example if

user='user1'password='password123'

then encodedCredentials will take the value

<encodedCredentials>dXNlcjE6cGFzc3dvcmQxMjM=</encodedCredentials>

OAuth

Linking API configuration with OAuth configuration

Another configurable method available is OAuth (in server-to-server flow). To add such configuration to an API you should:

• create an oAuth for the chosen id

• attribute in the api create an authorization with type oAuth

• in authorization define the id configuration

<api ...>
    <authorization type="oAuth">
        <id>oAuthConfigurationId</id>
    </authorization>
</api>
<oAuth id="oAuthConfigurationId" .../>

OAuth configuration parameters

An oAuth configuration consists of many parameters, all of which except authorization and additionalParams are set as attributes. The exception authorization and additionalParams are defined as nested elements. For example:

<oAuth id="oAuthConfig"
       url="http://localhost:8080/auth/token/"
       grantType="password"
       clientAuthenticationMethod="client_secret_post"
       clientId="yWSvwymlcvB9UoJFvBENscapghxqGy0u"
       clientSecret="jkIWQJM5Iv4mWyQV8RJv28wGRNJq276JttSeCQjkwMDdQpSgqW0YH7NM46pdu7ePGrI9kvuwqC9E76EiMEoOPu5TzdcJEdiX"
       username="admin"
       password="secretpassword">
    <authorization type="basic">
        <encodedCredentials>dXNlcjpwYXNzd29yZAo==</encodedCredentials>
    </authorization>
    <additionalParams>
        <language>pl</language>
    <additionalParams>
</oAuth>

Parameter	Required	Description
id	Yes	Identifier of the OAuth configuration, referenced in the API configuration.
description	No	Description of the given OAuth configuration.
url	Yes	Address used to generate the token, e.g. http://localhost:8080/oauth/token
grantType	Yes	Name of the selected grant type mechanism. Supported parameter values: client_credentials - token obtained based on clientId and clientSecret, password - token obtained based on additional username and password
clientAuthenticationMethod	Yes	Name of the selected client authentication mechanism. Supported parameter values: client_secret_post - credentials (clientId and clientSecret) in the request body, client_secret_basic - authentication using basic (clientId:clientSecret encoded base64).
clientId	Yes	Client identifier
clientSecret	Yes	Client secret ("password")
username	Only when grantType=password	The username parameter required for the password grant type.
password	Only when grantType=password	The password parameter required for the password grant type.
authorization	No	Parameter to be used when additional authorization needs to be defined for generating the token. Currently supports only basic type.
additionalParams	No	Parameter allowing definition of custom parameters for the token generation request. The configuration shown in the example above results in adding one parameter language with value pl.

Additional technical information

For OAuth authorization an additional mechanism is applied so that in case of receiving a 401 (Unauthorized) response the currently stored token is invalidated and the request is retried once.