> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/integrity-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/integrity-api/configuration.md).

# Configuration

API requires module API to be deployed. If endpoints are implemented in Pipes, the Pipes module must be deployed. 

{% hint style="info" %}
Since API is based on HTTP all HTTP configuration properties are supported. Find global settings [here](https://docs.fortifiedid.se/modules/configuration).
{% endhint %}

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="254">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>http_context</code></td><td>Base context (Default: <code>"/api"</code>)</td></tr><tr><td><code>endpoints</code></td><td>List of api endpoint configurations</td></tr><tr><td></td><td></td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
  "http_context" : "/api01",
  "endpoints" : [ ]
}
```

{% endtab %}
{% endtabs %}

## Endpoint configuration

Each API endpoint represents an API with a unique context path and configurable authentication and request/response data. Endpoint logic can be implemented by a pipe but it is not required.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="254">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>Endpoint name (Mandatory)</td></tr><tr><td><code>context_path</code></td><td>Endpoint relative path (Optional, defaults to name)</td></tr><tr><td><code>public</code></td><td>Flag turning on/off authentication for this endpoint (Default: <code>false</code>)</td></tr><tr><td><code>auth.*</code></td><td>Endpoint authentication configuration</td></tr><tr><td><code>auth.pipe</code></td><td>Id of pipe performing endpoint authentication. Authentication is successful if pipe returns success, otherwise authentication fails. Request and response handlers are only called if authentication is successful.</td></tr><tr><td><code>request.*</code></td><td>Request configuration (see below for handler specific configuration)</td></tr><tr><td><code>request.handler</code></td><td>Name of request handler (Default: <code>"Pipes"</code>)</td></tr><tr><td><code>response.*</code></td><td>Response configuration (see below for handler specific configuration)</td></tr><tr><td><code>response.handler</code></td><td>Name of response handler (Default: <code>"Pipes"</code>)</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
{
    "name" : "svc01",
    "public" : true,
    "auth" : {
      "pipe" : "auth_pipe_01"
    },
    "request" : {
      "handler" : "DataProxy",
      "pipe" : "api_pipe_01"
    },
    "response" : {
      "handler" : "DataProxy"
    }
}
```

{% endtab %}
{% endtabs %}

### Request handlers

The request handler is a pluggable component responsible for processing the endpoint HTTP request.&#x20;

#### Pipes

This is the default handler. Converts the API HTTP request to a pipe request containing the body, configured headers and params and request properties.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="254">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>pipe</code></td><td>Id of pipe implementing the endpoint</td></tr><tr><td><code>headers</code></td><td>List of headers to include in pipe request. (Default: <code>null</code>, no headers are included)</td></tr><tr><td><code>params</code></td><td>List of parameters (query and/or form) to include in pipe request. (Default: <code>"*"</code>, all params are included)</td></tr><tr><td><code>session_overload</code></td><td>Flag to enable session overload (i.e use specific session when calling pipes) (Default: <code>false</code>)</td></tr><tr><td><code>session_id</code></td><td>Name of request parameter containing session id for session overloading. (Default: <code>"__session_id"</code>)</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"request": {
    "handler": "Pipes",
    "pipe": "pipe_01",
    "headers": "Host",
    "params": "*",
    "session_overload": true,
    "session_id": "token"
}
```

{% endtab %}
{% endtabs %}

#### ProxyData

This request handler proxies request data (i.e. the body) without modifications to a pipe. If request data is a form a new pipe request will be built containing all form params.

### Response handlers

The response handler is a pluggable component responsible for producing the endpoint HTTP response.&#x20;

{% hint style="info" %}
Response handlers can only be combined with request handlers producing a compatible output.
{% endhint %}

#### Pipes

This is the default handler. Operates on pipe responses that may contain items. Produces a custom response body using a template or returns the pipe response as-is if no template is configured (JSON).

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="254">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>content_type</code></td><td>Response content type</td></tr><tr><td><code>template</code></td><td>Response template (see below)</td></tr><tr><td><code>status</code></td><td>Custom status configuration (see below)</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"response": {
    "handler": "Pipes",
    "content_type": "application/json",
    "template": ""
}
```

{% endtab %}
{% endtabs %}

#### ProxyData

Response handler creating a response from a pipe response containing headers and body properties.

### Response templating

When using the Pipes response handler, the  response can be transformed to any text format using a template.

#### Template scope objects

The following object are available during template rendering:

| Name        | Description                         |
| ----------- | ----------------------------------- |
| `items`     | List of response items              |
| `response`  | The actual response                 |
| `util.now`  | Current date/time as an ISO instant |
| `util.uuid` | Create UUID                         |

#### Example template

```json
{
    "now": "{{util.now}}",
    "count": {{items.size}},
    "elems": [
        {{#items}}
        { "id": "{{id}}" }
        {{/items}}
    ]
}
```

```json
{{{response}}}
```

### Status mapping

Pipe response reason can be mapped to a custom HTTP status code by using status mappings.

Mappings are processed in the defined order, first match wins.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="254">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>regex</code></td><td>Regular expression matched against reason string</td></tr><tr><td><code>value</code></td><td>The HTTP status code returned on match</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

<pre class="language-json"><code class="lang-json">"status": [
<strong>  {
</strong>    "regex" : "Not found",
    "value" : 404
  },
  {
    "regex" : "Custom status.*",
    "value" : 444
  },
  {
    "regex" : ".{1,}",
    "value" : 500
  }  
]
</code></pre>

{% endtab %}
{% endtabs %}

### Default configuration file

Attached is the default config.json file used when starting the default configuration.

{% file src="/files/nP4qjOW2fFQm47NZbdQr" %}