Rest API 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 address, but an alias, which is mapped to the actual service address based on the platform configuration.
This 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, this information is included both in the documentation and in configuration requests.
Configuration
For security reasons, references to external services must be specified in the configuration (serviceId).
The configuration is loaded and processed once when the platform starts. This means that additional changes in the references will require restarting the application (webforms-rest).
The configuration is read from 2 sources at the same time (provided 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 used (reading order from top to bottom).
It is possible to use the endpoint from one specific serviceId definition in another. 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: "pierwszyServiceId"
url: "https://moj.namiar" # endpoint: https://moj.namiar
- serviceId: "drugiServiceId"
url: "pierwszyServiceId/endpoint" # endpoint: https://moj.namiar/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 service A configuration dependent on B, which will depend 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:
Configuration after loading:
Authentication
Basic
There is also the possibility to define "Basic" authentication per service. The 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 at the script service level (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.
Value in the tag encodedCredentials is defined by base64-encoding the value
For example, if
then encodedCredentials will take the value
OAuth
Linking API configuration with OAuth configuration
Another configurable method is oAuth (in a server-to-server flow). To add such a configuration to the API, you need to:
create an oAuth configuration oAuth for the selected id
in the element api create authorization with the type oAuth
in authorization define id configuration
OAuth configuration parameters
An oAuth configuration consists of many parameters, all except authorization and additionalParams are set as attributes. The exception authorization and additionalParams are defined as nested elements. For example:
id
Yes
OAuth configuration identifier, indicated 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 - basic authentication (clientId:clientSecret encoded in 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 use when it is necessary to define additional authorization for generating the token.
Currently supports only the basic type.
additionalParams
No
Parameter allowing custom parameters for the token generation request to be defined. The configuration shown in the above translation results in adding one language parameter with the value pl.
Additional technical information
For OAuth authorization, an additional mechanism is used so that in the event of a response with status 401 (Unauthorized), the currently stored token is invalidated and the request is retried once.
Last updated
Was this helpful?