# Konfiguracja RestApi

## ServiceId <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-konfiguracja" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-konfiguracja"></a>

ServiceId to **unikalny identyfikator logiczny usługi**, wykorzystywany w skryptach, zadaniach skryptowych i modelu danych do odwoływania się do konkretnego endpointu REST.\
Nie jest to bezpośredni adres URL, lecz **alias**, który jest **mapowany na rzeczywisty adres usługi** na podstawie konfiguracji platformy.

\
Taki sposób korzystania z usług zapewnia elastyczność we wskazywaniu adresów na poszczególnych środowiskach i administratorzy mogą łatwo zmieniać adres na jednym ze środowisk. Przy migracjach bardzo ważne jest, aby po zaktualizowaniu serviceId lub dodaniu nowej usługi informacja o tym znalazła się zarówno w dokumentacji, jak i w zgłoszeniach konfiguracyjnych.

## Konfiguracja <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-konfiguracja" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-konfiguracja"></a>

Ze względów bezpieczeństwa, namiary na usługi zewnętrzne muszą zostać wskazane w konfiguracji (serviceId).

Konfiguracja ładuje się i przetwarza jednorazowo przy starcie platformy. Oznacza to, że dodatkowe zmiany w namiarach będą wymagały restartu aplikacji (webforms-rest).

Konfiguracja jest czytana z 2 źródeł jednocześnie (dostarczone propertiesy oraz zewnętrzny plik XML). Oba źródła są opcjonalne i nie blokują podniesienia się aplikacji.\
Jeśli wystąpi konflikt nazw dla serviceId, uwzględniony zostanie ostatni załadowany z listy (kolejność czytania od góry do dołu).

Istnieje możliwość wykorzystania namiaru z definicji konkretnego serviceId w innym.\
Aby skorzystać z tej opcji, należy zdefiniować pierwszy serviceId, a następnie w namiarze dla drugiego podać nazwę pierwszego serviceId.\
Np.

```
scriptservice:
    api:
        - serviceId: "pierwszyServiceId"
          url: "https://moj.namiar"    # namiar: https://moj.namiar
        - serviceId: "drugiServiceId"
          url: "pierwszyServiceId/endpoint"   # namiar: https://moj.namiar/endpoint
          authorization:
            type: basic
            encodedCredentials: cGFzc3dvcmQ=

```

{% hint style="warning" %}
Skorzystanie z innego namiaru do zdefiniowania nowej konfiguracji działa poprawnie tylko do 1 zagłębienia (zależności: A → B).

Oznacza to, że **nie możemy** mieć konfiguracji usługi A zależnej od B, która będzie zależna od C (zależności: A → B → C).
{% endhint %}

### Konfiguracja XML <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-konfiguracjaxml" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-konfiguracjaxml"></a>

Dla skryptów oraz walidatorów skryptowych:

Plik o nazwie "**script-service-api.xml**" powinien znajdować się w **`/etc/eximee/webforms/script-code-config`**.

Dla handlerów skryptowych:

Plik o nazwie "**script-handler-api.xml**" powinien znajdować się w **`/etc/eximee/webforms/script-handler-config`**.

{% hint style="info" %}
Plik musi być ręcznie modyfikowany przez administratorów
{% endhint %}

Struktura pliku:

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<scriptservice>
    <api serviceId="mojServiceId"
         url="http://moj.namiar"
         description="Opis dla podpowiedzi w Eximee Designer">
        <authorization type="basic">
            <encodedCredentials>cGFzc3dvcmQ=</encodedCredentials>
        </authorization>
    </api>
    <api serviceId="nbp"
         url="http://api.nbp.pl/api"
         description="Namiar do api udostępnionego przez NBP" />
    <api serviceId="nbpExchange"
         url="nbp/exchangerates"
         description="Namiar na api od NBP dotyczącego kursu walut" />
</scriptservice>
```

Konfiguracja po załadowaniu:

```
{
    "nbpExchange": {
        "url": "http://api.nbp.pl/api/exchangerates",
        "description": "Namiar na api od NBP dotyczącego kursu walut"
    },
    "mojServiceId": {
        "url": "http://moj.namiar",
        "description": "Opis dla podpowiedzi w Eximee Designer"
    },
    "nbp": {
        "url": "http://api.nbp.pl/api",
        "description": "Namiar do api udostępnionego przez NBP"
    }
}
```

## Uwierzytelnianie <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-uwierzytelnianie" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-uwierzytelnianie"></a>

### Basic <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-basic" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-basic"></a>

Istnieje możliwość zdefiniowana uwierzytelniania typu "Basic" per usługa.\
Konfiguracji dokonuje się w tym samym pliku, który definiuje namiary na usługę. Przykład przedstawiono powyżej (należy zwrócić uwagę na sekcję "authorization")\
Zdefiniowanie nagłówka "Authorization" z poziomu serwisu skryptowego (tzw "hardcode") spowoduje wygenerowanie ostrzeżenia w logach.\
Jeśli w definicji usługi (w pliku) podano sposób uwierzytelnienia ma on priorytet i zastąpi nagłówek "Authorization" będący zaszyty w pliku z serwisem skryptowym.

<br>

Wartość w tagu *encodedCredentials* definiujemy poprzez zabase'owanie wartości

```
login:hasło
```

Na przykład jeśli

```
user='user1'password='password123'
```

to *encodedCredentials* przyjmie wartość

```
<encodedCredentials>dXNlcjE6cGFzc3dvcmQxMjM=</encodedCredentials>
```

### OAuth <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-oauth" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-oauth"></a>

#### Powiązanie konfiguracji API z konfiguracją OAuth <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-powiazaniekonfiguracjiapizkonfiguracjaoauth" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-powiazaniekonfiguracjiapizkonfiguracjaoauth"></a>

Kolejną dostępną do skonfigurowania metodą jest oAuth (w przepływie server-to-server). Chcąc dodać taką konfigurację do API należy:

* utworzyć konfigurację **oAuth** o wybranym **id**
* w elemencie **api** utworzyć **authorization** z typem **oAuth**
* w **authorization** zdefiniować **id** konfiguracji

```xml
<api ...>
    <authorization type="oAuth">
        <id>idKonfiguracjiOAuth</id>
    </authorization>
</api>
<oAuth id="idKonfiguracjiOAuth" .../>
```

#### Parametry konfiguracji OAuth <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-parametrykonfiguracjioauth" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-parametrykonfiguracjioauth"></a>

Na konfigurację oAuth składa się wiele parametrów, z których wszystkie poza **authorization** i **additionalParams** ustawiane są jako atrybuty. Będące wyjątkiem **authorization** i **additionalParams** definiowane są jako zagnieżdżone elementy. Przykładowo:

```xml
<oAuth id="oAuthConfig"
       url="http://localhost:8080/auth/token/"
       grantType="password"
       clientAuthenticationMethod="client_secret_post"
       clientId="yWSvwymlcvB9UoJFvBENscapghxqGy0u"
       clientSecret="jkIWQJM5Iv4mWyQV8RJv28wGRNJq276JttSeCQjkwMDdQpSgqW0YH7NM46pdu7ePGrI9kvuwqC9E76EiMEoOPu5TzdcJEdiX"
       username="admin"
       password="tajnehaslo">
    <authorization type="basic">
        <encodedCredentials>dXNlcjpwYXNzd29yZAo==</encodedCredentials>
    </authorization>
    <additionalParams>
        <language>pl</language>
    <additionalParams>
</oAuth>
```

| Parametr                       | Wymagany                     | Opis                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **id**                         | Tak                          | Identyfikator konfiguracji oAuth, wskazywany w konfiguracji api.                                                                                                                                                                                                                                                                                   |
| **description**                | Nie                          | Opis danej konfiguracji OAuth.                                                                                                                                                                                                                                                                                                                     |
| **url**                        | Tak                          | Adres służący do generowania tokenu, np. <http://localhost:8080/oauth/token>                                                                                                                                                                                                                                                                       |
| **grantType**                  | Tak                          | <p>Nazwa wybranego mechanizmu grant type.</p><p>Obsługiwane wartości parametru:</p><ul><li><strong>client\_credentials -</strong> token uzyskiwany na podstawie clientId i clientSecret,</li><li><strong>password -</strong> token uzyskiwany na podstawie dodatkowego username i password</li></ul>                                               |
| **clientAuthenticationMethod** | Tak                          | <p>Nazwa wybranego mechanizmu uwierzytelnienia klienta.</p><p>Obsługiwane wartości parametru:</p><ul><li><strong>client\_secret\_post -</strong> dane uwierzytelniające (clientId i clientSecret) w body requestu,</li><li><strong>client\_secret\_basic -</strong> uwierzytelnienie basiciem (clientId:clientSecret zakodowane base64).</li></ul> |
| **clientId**                   | Tak                          | Identyfikator klienta                                                                                                                                                                                                                                                                                                                              |
| **clientSecret**               | Tak                          | Sekret ("hasło") klienta                                                                                                                                                                                                                                                                                                                           |
| **username**                   | Tylko gdy grantType=password | Parametr username wymagany na potrzeby grant type password.                                                                                                                                                                                                                                                                                        |
| **password**                   | Tylko gdy grantType=password | Parametr password wymagany na potrzeby grant type password.                                                                                                                                                                                                                                                                                        |
| **authorization**              | Nie                          | <p>Parametr do wykorzystania w przypadku, gdy potrzebne jest zdefiniowanie dodatkowej autoryzacji na potrzeby wygenerowania tokenu.</p><p>Obecnie wspiera tylko typ basic.</p>                                                                                                                                                                     |
| **additionalParams**           | Nie                          | Parametr pozwalający zdefiniować niestandardowe parametry żądania o wygenerowanie tokenu. Przedstawiona w powyższym przekładzie konfiguracja skutkuje dodaniem jednego parametru language o wartości pl.                                                                                                                                           |

#### Dodatkowe informacje techniczne <a href="#id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-dodatkoweinformacjetechniczne" id="id-restapi-wolaniezewnetrznychuslugrestowych-scriptcode-dodatkoweinformacjetechniczne"></a>

Dla autoryzacji OAuth zastosowany jest dodatkowo mechanizm powodujący, że w przypadku uzyskania odpowiedzi ze statusem 401 (Unauthorized) przechowywany obecnie token zostaje unieważniony, a żądanie zostaje jednokrotnie ponowione.


---

# 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/budowanie-aplikacji/logika-biznesowa/scriptcode/restapi-integracje-z-zewnetrznymi-systemami/konfiguracja-restapi.md?ask=<question>
```

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.