# REST Adapter configuration

This page describes configuration for the Liberator REST Adapter.

**Available from:** Liberator 8.0.0

**Requires:** 17/21, Caplin StreamLink 8.0.0, Caplin Deployment Framework 8.0.0

## Configuration file location

The REST Adapter kit packaged with Liberator includes two configuration files:

**Configuration file location in a Deployment Framework**

```plantuml
@startsalt
scale 1.25
{
{T
 + <color:goldenrod><&folder></color> DeploymentFramework-//version//
 ++ <color:goldenrod><&folder></color> global_config
 +++ <color:goldenrod><&folder></color> overrides
 ++++ <color:goldenrod><&folder></color> LiberatorRESTAdapter
 +++++ <color:goldenrod><&folder></color> DataSource
 ++++++ <color:goldenrod><&folder></color> etc
 +++++++ <color:cornflowerblue><&file></color> **datasource.conf** | <color:gray>REST Adapter configuration</color>
 +++++ <color:goldenrod><&folder></color> Liberator
 ++++++ <color:goldenrod><&folder></color> etc
 +++++++ <color:cornflowerblue><&file></color> **rttpd.conf** | <color:gray>Liberator data service configuration</color>
}
}
@endsalt
```

## Configuration items

Configuration file: `global_config/overrides/LiberatorRESTAdapter/etc/datasource.conf`.

### add-rest-mapping

Publish a subject that proxies a REST endpoint.

**Syntax**

```macros"
add-rest-mapping
    <<accept-all-certificates,accept-all-certificates>>  _boolean_
    <<attribute-map,attribute-map>>  _string_  _string_
    <<auth-username,auth-username>>   _string_
    <<auth-password,auth-password>>   _string_
    <<base-url,base-url>>        _string_
    <<http-header,http-header>>     _string_ _string_
    <<subject-prefix,subject-prefix>>  _string_
end-rest-mapping
```

<a name="accept-all-certificates"></a>**Options**

* **`accept-all-certificates <boolean>`**\
[Optional] This setting should be used to indicate that the REST Adapter should accept any certificate from the REST API service when an SSL connection is established.

  <a name="accept-all-certificates"></a>Default value: `false`

  <a name="accept-all-certificates"></a>Example: `accept-all-certificates true`

* **`attribute-map _substitution_token_  _attribute_name_`**\
[Optional] A mapping from a substitution token used in the subject-prefix ([`subject-prefix`](#subject-prefix)) to an attribute which should be added to the JSON request payload. (See [JSON Payload Manipulation](../../caplin-platform/liberator/liberator-rest-adapter.md#json-payload-manipulation).)

  <a name="attribute-map"></a>Example: `attribute-map %1 currency_name`

* **`auth-username _username_`**\
[Optional] ["Basic" HTTP authentication scheme](https://datatracker.ietf.org/doc/html/rfc7617) credential.

  <a name="auth-username"></a>Example: `auth-username admin`

* **`auth-password _password_`**\
[Optional] ["Basic" HTTP authentication scheme](https://datatracker.ietf.org/doc/html/rfc7617) credential.

  <a name="auth-password"></a>Example: `auth-password password1234`

* **`base-url _URL_`**\
The REST service base URL to map to a subject-prefix ([`subject-prefix`](#subject-prefix)).

  <a name="base-url"></a>Example: `base-url https://api.open-meteo.com/v1/`

* **`http-header _header_name_  _header_value_`**\
[Optional] An HTTP header that the REST Adapter must include in every request to the REST service. Can be used multiple times to specify more than one header.

  <a name="http-header"></a>Example: `http-header X-Access-Token b1e6e452c26011edafa1`

* **`subject-prefix _prefix_`**\
The subject prefix to map to a REST service base URL ([`base-url`](#base-url)).

  <a name="subject-prefix"></a>Example: `subject-prefix /WEATHER/`

  <a name="subject-prefix"></a>The subject prefix can contain a numbered capture group as `%n`, where `n` is a number from 1 to 9. This makes it possible to include the captured token in the JSON request payload which is sent to the REST service. See [`attribute-map`](#attribute-map).

  <a name="subject-prefix"></a>Example: `subject-prefix /WEATHER/%1`

### demo-rest-api-credentials

[Optional] Specifies credentials for the REST Adapter’s built-in demo REST service. By default, no credentials are specified and no one can access the demo REST service. Only one set of credentials can be specified.

**Syntax:** `demo-rest-api-credentials _username_ _password_`

**Requires:** [enable-demo-rest-api](#enable-demo-rest-api), [rest-api-port](#rest-api-port)

**Default:** _none_

**Example:** `demo-rest-api-credentials user1 user1password`

### enable-demo-rest-api

[Optional] Enable the demo REST API in the REST Adapter. (See [Enabling the demo REST API service in the REST Adapter](../../caplin-platform/liberator/liberator-using-rest-adapter#enable-demo-rest-api).)

**Syntax:** `enable-demo-rest-api  _boolean_`

**Default:** `false`

**Requires:** [rest-api-port](#rest-api-port), [demo-rest-api-credentials](#demo-rest-api-credentials)

**Example:** `enable-demo-rest-api  true`

**⚠️ WARNING**\
The demo REST API is provided for testing purposes only and should be disabled when using the REST Adapter in production.

### payload-max-size

This setting determines the maximum HTTP response payload size (in MB) that the REST Adapter is able to handle when [mapping to a JSON response](../../caplin-platform/liberator/liberator-rest-adapter#rest-payloads).

**Syntax:** `payload-max-size _integer_` 

**Default:** `1`

**Valid values:** 1 to 5 (MB)

**Example:** `payload-max-size 2`

### rest-api-port

Specifies the port number of the adapter’s built-in REST server. Required for [enable-demo-rest-api](#enable-demo-rest-api).

**Syntax:** `rest-api-port <port>`

**Default:** _none_

**Example:** `rest-api-port 8099`

### SslKeyStorePath

Path to a TLS client-certificate KeyStore, containing a single certificate that identifies the REST Adapter in TLS mutual-authentication certificate exchanges.

This configuration is not set by default and is only required if one or more REST endpoints require TLS mutual-authentication. Follow instructions in the Java 11 [`keytool`](https://docs.oracle.com/en/java/javase/11/tools/keytool.html) documentation to create a PFX KeyStore and import a client-certificate signed by a trusted CA.

**Syntax**

```
SslKeyStorePath        __absolute_path__
```

**Example**

```
SslKeyStorePath        ${ENV:CONFIG_BASE}/overrides/LiberatorRESTAdapter/DataSource/etc/clientcert.pfx
```

### SslKeyStorePassword

Password to the client-certificate KeyStore ([`SslKeyStorePath`](#sslkeystorepath)).

**Syntax**

```
SslKeyStorePassword    __password__
```

**Example**

```
SslKeyStorePassword    changeit
```

### SslTrustStorePath

Path to a CA certificate TrustStore, containing CA certificates trusted by the REST Adapter.

By default, the REST Adapter uses the default Java TrustStore.

**Syntax**

```
SslTrustStorePath      __absolute_path__
```

**Example**

```
SslTrustStorePath      ${ENV:JAVA_HOME}/lib/security/cacerts
```

### SslTrustStorePassword

Password to the CA certificate TrustStore ([`SslTrustStorePath`](#ssltruststorepath)).

**Syntax**

```
SslTrustStorePassword  __password__
```

**Example**

```
SslTrustStorePassword  changeit
```

---

**See also:**

* [Liberator REST adapter](liberator-rest-adapter.md)
* [Enabling the REST adapter](liberator-rest-enabling.md)