# 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 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 particular 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 at platform startup. 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 up.\ 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). It is possible to use the reference from the definition of one specific serviceId in another.\ To use this option, define the first serviceId, and then provide the name of the first serviceId in the reference for the second one.\ E.g. ``` 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= ``` {% hint style="warning" %} 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's configuration dependent on B, which will be dependent on C (dependencies: A → B → C). {% endhint %} ### 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`**. {% hint style="info" %} The file must be manually modified by administrators {% endhint %} File structure: ```xml cGFzc3dvcmQ= ``` Configuration after loading: ``` { "nbpExchange": { "url": "http://api.nbp.pl/api/exchangerates", "description": "Reference to the NBP API regarding exchange rates" }, "mojServiceId": { "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 reference. 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 hardcoded 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* it will take the value ``` dXNlcjE6cGFzc3dvcmQxMjM= ``` ### OAuth #### Linking API configuration with OAuth configuration Another method available for configuration is oAuth (in the server-to-server flow). To add such a configuration to an API, you need to: * create the **oAuth** configuration with the selected **id** * in the **api** element, create **authorization** with type **oAuth** * in **authorization** define **id** configuration ```xml oauthConfigId ``` #### OAuth configuration parameters The oAuth configuration consists of many parameters, all of which except **authorization** and **additionalParams** are set as attributes. The exception is **authorization** and **additionalParams** defined as nested elements. For example: ```xml dXNlcjpwYXNzd29yZAo== pl ``` | Parameter | Required | Description | | ------------------------------ | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **id** | Yes | The oAuth configuration identifier, indicated in the api configuration. | | **description** | No | Description of the given OAuth configuration. | | **url** | Yes | The address used to generate the token, e.g. | | **grantType** | Yes |

Name of the selected grant type mechanism.

Supported values of the parameter:

| | **clientAuthenticationMethod** | Yes |

Name of the selected client authentication mechanism.

Supported values of the parameter:

| | **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 used when it is necessary to define additional authorization for the purpose of generating a token.

Currently supports only the basic type.

| | **additionalParams** | No | A parameter allowing the definition of custom parameters for the token generation request. The configuration shown in the translation above results in adding one language parameter with the value pl. | #### Additional technical information For OAuth authorization, an additional mechanism is used that causes the currently stored token to be invalidated in the event of a response with status 401 (Unauthorized), and the request is retried once. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami/konfiguracja-restapi.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.