> For the complete documentation index, see [llms.txt](https://docs.eximee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami/konfiguracja-restapi.md). # 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= ``` {% hint style="warning" %} 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). {% 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": "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 ``` dXNlcjE6cGFzc3dvcmQxMjM= ``` ### 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 ```xml 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: ```xml dXNlcjpwYXNzd29yZAo== pl ``` | 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. | | **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).

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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.eximee.com/documentation/documentation-en/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami/konfiguracja-restapi.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.