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.
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 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 configuration (serviceId).
Configuration is loaded and processed once at platform startup. This means that additional changes to references will require restarting the application (webforms-rest).
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 naming conflict for serviceId occurs, 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 one. To use this option, 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 level of nesting (dependencies: A → B).
This means that we cannot have service A 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.
File structure:
Configuration after loading:
Authentication
Basic
It is possible to define "Basic" type authentication per service. Configuration is done in the same file that defines the service references. An example is shown above (pay attention to 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 embedded in the script service file.
The 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 available is OAuth (in a server-to-server flow). To add such configuration to the 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
OAuth configuration parameters
The OAuth configuration consists of many parameters, all of which except authorization and additionalParams are set as attributes. Being an exception, authorization and additionalParams they are defined as nested elements. For example:
id
Yes
Identifier of the OAuth configuration, referenced in the api configuration.
description
No
Description of the OAuth configuration.
url
Yes
Address used to generate the token, e.g. http://localhost:8080/oauth/token
grantType
Yes
Name of the chosen 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 chosen client authentication mechanism.
Supported parameter values:
client_secret_post - credentials (clientId and clientSecret) in the request body,
client_secret_basic - authentication using basic auth (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
A parameter to use when additional authorization needs to be defined for generating the token.
Currently supports only the basic type.
additionalParams
No
A parameter that allows defining custom parameters for the token generation request. The configuration shown above results in adding one parameter language with the value pl.
Additional technical information
For OAuth authorization an additional mechanism is applied that, in case of receiving a 401 (Unauthorized) response, invalidates the currently stored token and the request is retried once.
Last updated
Was this helpful?