RestApi configuration

ServiceId

ServiceId is a unique logical identifier of the 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 platform configuration.

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

Configuration

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

Configuration is loaded and processed once at platform startup. This means that additional changes in the endpoints will require restarting the application (webforms-rest).

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

There is an option to use the endpoint from the definition of a specific serviceId in another one. To use this option, first define the first serviceId, and then in the endpoint for the second one provide the name of the first serviceId. E.g.

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

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

This means that we cannot have a configuration of service A depending on B, which will depend on C (dependencies: A → B → C).

XML configuration

For scripts and script validators:

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

For script handlers:

The 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.endpoint"
         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="Endpoint to the API provided by NBP" />
    <api serviceId="nbpExchange"
         url="nbp/exchangerates"
         description="Endpoint to the NBP API regarding exchange rates" />
</scriptservice>

Configuration after loading:

{
    "nbpExchange": {
        "url": "http://api.nbp.pl/api/exchangerates",
        "description": "Endpoint to the NBP API regarding exchange rates"
    },
    "myServiceId": {
        "url": "http://my.endpoint",
        "description": "Description for hints in Eximee Designer"
    },
    "nbp": {
        "url": "http://api.nbp.pl/api",
        "description": "Endpoint 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 endpoint. An example is shown above (pay attention to the "authorization" section) Defining the "Authorization" header from the script service level (the so-called "hardcode") will generate a warning in the logs. If the authentication method is specified in the service definition (in the file), it has priority and will replace the "Authorization" header embedded in the script service file.

The value in the tag encodedCredentials is defined by base64-encoding the value

login:password

For example, if

user='user1'password='password123'

then encodedCredentials will take the value

<encodedCredentials>dXNlcjE6cGFzc3dvcmQxMjM=</encodedCredentials>

OAuth

Association of API configuration with OAuth configuration

Another configurable method is oAuth (in the server-to-server flow). To add such a configuration to the API, you need to:

• create the configuration oAuth for the selected id
• in the element api create authorization of type oAuth
• in authorization define 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 being 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	OAuth configuration identifier, 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 values of the parameter: 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 values of the parameter: client_secret_post - authentication data (clientId and clientSecret) in the request body, client_secret_basic - basic authentication (clientId:clientSecret encoded in base64).
clientId	Yes	Client identifier
clientSecret	Yes	Client secret ("password")
username	Only when grantType=password	Username parameter required for the password grant type.
password	Only when grantType=password	Password parameter required for the password grant type.
authorization	No	Parameter to use when additional authorization needs to be defined for token generation. Currently only supports basic type.
additionalParams	No	Parameter allowing custom parameters of the request for token generation to be defined. The configuration shown in the above translation results in adding one language parameter with value pl.

Additional technical information

For OAuth authorization, an additional mechanism is used that causes the currently stored token to be invalidated and the request retried once if a response with status 401 (Unauthorized) is received.