# API Trigger

The **API Trigger** exposes an integration through a REST endpoint. When a pipeline is configured and deployed with this trigger, a REST endpoint is automatically generated. You can view this endpoint on the pipeline card in the **Run** page after deployment.

## **Routes List configuration**

To start configuring the trigger, follow these steps to set up the **Routes List**:

1. In the **Routes List** section, click **Add**.
2. Enter the **Path** (for example, "/users").
3. Select the appropriate **Method**.
4. Add a description in the **Summary** (such as "Retrieves all users").

After creating the route, it will appear in the **Routes List**. You can **add** new routes, **edit** existing routes, or **delete** them.

{% hint style="info" %}
Alternatively, you can create a pipeline with an OpenAPI specification file. Learn more about [how to scaffold a pipeline using an OpenAPI specification](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/build-overview/pipelines/how-to-scaffold-a-pipeline-using-an-openapi-specification).
{% endhint %}

### **Visual representation of the routes**

Once you save the configuration of the trigger, a visual representation of the routes is displayed in the pipeline.

<figure><img src="https://content.gitbook.com/content/EKM2LD3uNAckQgy1OUyZ/blobs/dcFd2vplqZ7nOxtKAzSP/image1.png" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The routes can only be edited through the trigger's configuration form. After saving, any changes will be immediately reflected in the pipeline.
{% endhint %}

Each route is connected to a [**Block Execution**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/logic/block-execution) connector, which is designed to logically separate the integration into different subflows for easier pipeline management. To complete the configuration, you will need to create the flows for each route within the [**OnProcess**](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/build-overview/pipelines/subpipelines#onprocess) and [**OnException**](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/build-overview/pipelines/subpipelines#onexception) subflows.

{% hint style="warning" %}
**Important information:**

* If you create the flow before configuring the trigger, the existing connectors will be disconnected once the trigger is configured.
* Deleting a route from the **Routes List** will disconnect the [**Block Execution**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/logic/block-execution) connector for that route from the main flow.
* Changing the **API Trigger** to another type of trigger will convert the **Router** into a [**Choice**](https://docs.digibee.com/documentation/connectors-and-triggers/connectors/logic/choice) connector, and the previously configured routes will automatically be connected to the **Choice**.

In each of these cases, you can copy the connectors within each **Block Execution** and paste them elsewhere in the pipeline.
{% endhint %}

## **Parameters**

Take a look at the configuration parameters for the trigger. Parameters supported by [Double Braces expressions](https://docs.digibee.com/documentation/connectors-and-triggers/double-braces/overview) are marked with `(DB)`.

<table data-full-width="true"><thead><tr><th>Parameter</th><th>Description</th><th>Default value</th><th>Data type</th></tr></thead><tbody><tr><td><strong>Maximum Timeout</strong></td><td>Maximum time (in milliseconds) for the pipeline to process information before returning a response. Limit: 900000 ms.</td><td>30000</td><td>Integer</td></tr><tr><td><strong>The Maximum Allowed Request Size In Mb</strong></td><td>Maximum size of the payload (in MB). The maximum configurable size is 5 MB.</td><td>5</td><td>Integer</td></tr><tr><td><strong>Response Headers</strong> <code>(DB)</code></td><td>Headers returned by the endpoint when the pipeline processing is complete. This parameter is mandatory.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Add Cross-Origin Resource Sharing (CORS)</strong></td><td>Enables the addition of CORS headers.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>CORS Headers</strong></td><td>CORS headers returned by the endpoint when the pipeline processing is complete. Available only if the <strong>Add Cross-Origin Resource Sharing (CORS)</strong> parameter is active.</td><td>N/A</td><td>Key-value pair</td></tr><tr><td><strong>External API</strong></td><td>If active, publishes the API in an external gateway.</td><td>True</td><td>Boolean</td></tr><tr><td><strong>Internal API</strong></td><td>If active, publishes the API in an internal gateway. Both the <strong>External API</strong> and <strong>Internal API</strong> options can be active simultaneously.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>mTLS Enabled API</strong></td><td>If active, publishes the API to a dedicated gateway with mTLS enabled by default.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>API Key</strong></td><td>If active, the endpoint can only be consumed if an API key is configured on the Digibee Integration Platform.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Token JWT</strong></td><td>If active, the endpoint can only be consumed if a JWT token generated by another endpoint is sent. Read more in the article about <a href="../../connectors/security/digibee-jwt/digibee-jwt-implementation">JWT implementation</a>.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Basic Auth</strong></td><td>If active, the endpoint can only be consumed if Basic Auth is present in the request. This setting can be registered beforehand through the <a href="https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/settings/api-keys-consumers"><strong>Consumers</strong></a> page in the Digibee Integration Platform.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Rate Limit</strong></td><td>If active, applies rate limiting on the API gateway. Available only if the <strong>API Key</strong> or <strong>Basic Auth</strong> parameters are active.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Limit by</strong></td><td>Defines the entity to which the limits will be applied. Available only if the <strong>Rate Limit</strong> parameter is active.</td><td>API</td><td>String</td></tr><tr><td><strong>Aggregate by</strong></td><td>Defines the entity for aggregating the limits. Options: <strong>Consumer</strong> and <strong>Credential (API Key, Basic Auth)</strong>. Available only if the <strong>Rate Limit</strong> parameter is active.</td><td>Consumer</td><td>String</td></tr><tr><td><strong>Options</strong></td><td>Defines the limit of requests that can be made within a time interval. Available only if the <strong>Rate Limit</strong> parameter is active.</td><td>n/a</td><td>Options of Rate Limit</td></tr><tr><td><strong>Interval</strong></td><td>Defines the time interval for the limit of requests. Options: <strong>second</strong>, <strong>minute</strong>, <strong>hour</strong>, <strong>day</strong>, and <strong>month</strong>. Available only if you add a new <strong>Option</strong>.</td><td>second</td><td>String</td></tr><tr><td><strong>Limit</strong></td><td>Defines the maximum number of requests that users can make in the specified time interval. Available only if you add a new <strong>Option</strong>.</td><td>n/a</td><td>Integer</td></tr><tr><td><strong>Allow Redelivery Of Messages</strong></td><td>If active, allows the message to be resent if the Pipeline Engine fails. Read more in the article about the <a href="https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/overview/runtime/pipeline-engine">Pipeline Engine</a>.</td><td>False</td><td>Boolean</td></tr><tr><td><strong>Documentation</strong></td><td>Section for documenting any necessary information about the trigger configuration and business rules.</td><td>N/A</td><td>String</td></tr></tbody></table>

{% hint style="info" %}
There is a global configuration parameter that specifies that all pipelines must be published with at least the **API Key** or **Basic Auth** options enabled.
{% endhint %}

### **Parameters additional information**

Further details on the parameters can be found below:

<details>

<summary><strong>The Maximum Allowed Request Size In Mb</strong></summary>

If the payload sent by the endpoint consumer exceeds the limit, a message is returned indicating that the maximum size has been exceeded, along with a status code 413 and the following message:

```json
{  
   "message": "Request size limit exceeded"
}
```

</details>

<details>

<summary><strong>Add Cross-Origin Resource Sharing (CORS) - CORS Headers</strong></summary>

Cross-Origin Resource Sharing (CORS) is a mechanism that allows you to tell the browser which origins are allowed to make requests. This parameter defines CORS specifically for the pipeline and its constraints. To configure this globally and not individually for each pipeline, see the [CORS HTTP header policy](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/platform-administration/governance/policies/transformation/cors-http-header).

You can use a comma to enter multiple values in a header, but you should not insert a space before or after the comma. In addition, no special characters should be used in the keys, as this can lead to errors in proxies and gateways.

</details>

<details>

<summary><strong>mTLS enabled API</strong></summary>

You can enable the **External API** and **Internal API** options together with **mTLS enabled API**, but we recommend leaving them disabled. This parameter does not support **API Key**, **Token JWT**, or **Basic Auth**.

To use this in your realm, you need to make a request through support and we will send you the necessary information to install this service.

</details>

<details>

<summary><strong>Rate Limit</strong></summary>

When creating APIs, it’s common to limit the number of API requests that users can make in a given time interval.

You can do this by enabling the **Rate Limit** option and applying the following settings:

* **Limit:** API
* **Aggregate by:** Credential (API Key, Basic Auth)
* **Options:**
  * **Item 1:**
    * **Interval:** second
    * **Limit:** 100
  * **Item 2:**
    * **Interval:** minute
    * **Limit:** 1000
  * **Item 3:**
    * **Interval:** hour
    * **Limit:** 5000

If the API has additional paths, the limit is shared among all paths. To apply the rate limit settings, the API must be configured with an **API Key** or **Basic Auth**. In this way, the **Aggregate by** parameter can be used for groups of credentials if the **Consumer** option is selected, or for a single credential if the **Credential (API Key, Basic Auth)** option is selected.

If several interval parameters with repeating values are configured, only one of these values is taken into account. It’s also necessary that a value greater than zero is specified for the **Limit** parameter.

If the rate limit options are not set correctly, they are ignored and a warning log is issued. You can view this log on the [**Pipeline Logs**](https://app.gitbook.com/s/jvO5S91EQURCEhbZOuuZ/development-cycle/dashboards/pipeline-logs) page.

</details>