# API Trigger

O **API Trigger** expõe uma integração através de um endpoint REST. Quando um pipeline é configurado e implantado com esse trigger, um endpoint REST é gerado automaticamente. Você pode visualizar esse endpoint no cartão do pipeline na página [**Run**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/overview) após a implantação.

## **Configuração da Routes List**

Para começar a configurar o trigger, siga estes passos para configurar a **Routes List**:

1. Na seção **Routes List**, clique em **Adicionar**.
2. Insira o **Path** (por exemplo, "/users").
3. Selecione o **Method** apropriado.
4. Adicione uma descrição no campo **Summary** (como "Recupera todos os usuários").

Depois de criar a rota, ela aparecerá na **Routes List**. Você pode **adicionar** novas rotas, **editar** as rotas existentes ou **excluí-las**.

{% hint style="info" %}
Alternativamente, você pode criar um pipeline com um arquivo de especificação OpenAPI. Saiba mais sobre [como criar um pipeline a partir de uma especificação OpenAPI](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/pipelines/how-to-scaffold-a-pipeline-using-an-openapi-specification).
{% endhint %}

### **Representação visual das rotas**

Após salvar a configuração do trigger, uma representação visual das rotas será exibida no pipeline.

<figure><img src="https://content.gitbook.com/content/SKBJ6ZiEWBU93x170HH4/blobs/J7e8grG3wjOgvFuiZLm7/API%20Trigger%20(visual%20representation).png" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
As rotas só podem ser editadas através do formulário de configuração do trigger. Depois de salvar, quaisquer alterações serão refletidas imediatamente no pipeline.
{% endhint %}

Cada rota é conectada a um conector [**Block Execution**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/logic/block-execution), que é projetado para separar logicamente a integração em subfluxos diferentes, facilitando o gerenciamento do pipeline. Para concluir a configuração, você precisará criar os fluxos para cada rota dos subfluxos [**OnProcess**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/pipelines/subpipelines#onprocess) e [**OnException**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/pipelines/subpipelines#onexception).

{% hint style="warning" %}
**Informações importantes:**

* Se você criar o fluxo antes de configurar o trigger, os conectores existentes serão desconectados assim que o trigger for configurado.
* Excluir uma rota da **Routes List** irá desconectar o conector [**Block Execution**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/logic/block-execution) desta rota do fluxo principal.
* Alterar o **API Trigger** para outro tipo de trigger converterá o **Router** em um conector [**Choice**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/logic/choice), e as rotas configuradas anteriormente serão automaticamente conectadas ao **Choice**.

Em cada um desses casos, você pode copiar os conectores dentro de cada **Block Execution** e colá-los em outra parte do pipeline.
{% endhint %}

## **Parâmetros**

Dê uma olhada nos parâmetros de configuração do trigger. Parâmetros suportados por [expressões Double Braces](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/overview) estão marcados com `(DB)`.

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Valor padrão</th><th>Tipo de dado</th></tr></thead><tbody><tr><td><strong>Maximum Timeout</strong></td><td>Tempo máximo (em milissegundos) para o pipeline processar as informações antes de retornar uma resposta. Limite: 900000 ms.</td><td>30000</td><td>Integer</td></tr><tr><td><strong>The Maximum Allowed Request Size In Mb</strong></td><td>Tamanho máximo do payload (em MB). O tamanho configurável máximo é de 5 MB.</td><td>5</td><td>Integer</td></tr><tr><td><strong>Response Headers</strong> <code>(DB)</code></td><td>Headers retornados pelo endpoint quando o processamento do pipeline for concluído. Este parâmetro é obrigatório.</td><td>N/A</td><td>String</td></tr><tr><td><strong>Add Cross-Origin Resource Sharing (CORS)</strong></td><td>Habilita a adição de headers CORS.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>CORS Headers</strong></td><td>Headers CORS retornados pelo endpoint quando o processamento do pipeline for concluído. Disponível apenas se o parâmetro <strong>Add Cross-Origin Resource Sharing (CORS)</strong> estiver ativo.</td><td>N/A</td><td>Par de chave-valor</td></tr><tr><td><strong>External API</strong></td><td>Se ativo, publica a API em um gateway externo.</td><td>True</td><td>Booleano</td></tr><tr><td><strong>Internal API</strong></td><td>Se ativo, publica a API em um gateway interno. As opções <strong>External API</strong> e <strong>Internal API</strong> podem estar ativas simultaneamente.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>mTLS Enabled API</strong></td><td>Se ativo, publica a API em um gateway dedicado com mTLS habilitado por padrão.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>API Key</strong></td><td>Se ativo, o endpoint só pode ser consumido se uma chave de API estiver configurada na Digibee Integration Platform.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Token JWT</strong></td><td>Se ativo, o endpoint só pode ser consumido se um token JWT gerado por outro endpoint for enviado. Saiba mais no artigo sobre <a href="../../connectors/security/digibee-jwt/digibee-jwt-implementation">implementação do Digibee JWT</a>.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Basic Auth</strong></td><td>Se ativo, o endpoint só pode ser consumido se a autenticação Basic Auth estiver presente na requisição. Essa configuração pode ser registrada previamente na página <a href="https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/settings/api-keys-consumers"><strong>Consumers</strong></a> na Digibee Integration Platform.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Rate Limit</strong></td><td>Se ativo, aplica a limitação de taxa no gateway da API. Disponível apenas se os parâmetros <strong>API Key</strong> ou <strong>Basic Auth</strong> estiverem ativos.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Limit by</strong></td><td>Define a entidade à qual os limites serão aplicados. Disponível apenas se o parâmetro <strong>Rate Limit</strong> estiver ativo.</td><td>API</td><td>String</td></tr><tr><td><strong>Aggregate by</strong></td><td>Define a entidade para agregar os limites. Opções: <strong>Consumer</strong> e <strong>Credential (API Key, Basic Auth)</strong>. Disponível apenas se o parâmetro <strong>Rate Limit</strong> estiver ativo.</td><td>Consumer</td><td>String</td></tr><tr><td><strong>Options</strong></td><td>Define o limite de requisições que podem ser feitas dentro de um intervalo de tempo. Disponível apenas se o parâmetro <strong>Rate Limit</strong> estiver ativo.</td><td>N/A</td><td>Opções de Rate Limit</td></tr><tr><td><strong>Interval</strong></td><td>Define o intervalo de tempo para o limite de requisições. Opções: <strong>second</strong>, <strong>minute</strong>, <strong>hour</strong>, <strong>day</strong>, e <strong>month</strong>. Disponível apenas se uma nova opção (<strong>Option</strong>) for adicionada.</td><td>Second</td><td>String</td></tr><tr><td><strong>Limit</strong></td><td>Define o número máximo de requisições que os usuários podem fazer no intervalo de tempo especificado. Disponível apenas se uma nova opção (<strong>Option</strong>) for adicionada.</td><td>N/A</td><td>Integer</td></tr><tr><td><strong>Allow Redelivery Of Messages</strong></td><td>Se ativo, permite que a mensagem seja reenviada caso o Pipeline Engine falhe. Saiba mais no artigo sobre o <a href="https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/overview/runtime/pipeline-engine">Pipeline Engine</a>.</td><td>False</td><td>Booleano</td></tr><tr><td><strong>Documentation</strong></td><td>Seção para documentar qualquer informação necessária sobre a configuração do trigger e regras de negócio.</td><td>N/A</td><td>String</td></tr></tbody></table>

{% hint style="info" %}
Há um parâmetro de configuração global que especifica que todos os pipelines devem ser publicados com pelo menos as opções **API Key** ou **Basic Auth** habilitadas.
{% endhint %}

### **Informações adicionais dos parâmetros**

Abaixo você encontra mais detalhes sobre os parâmetros:

<details>

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

Se o payload enviado pelo consumidor do endpoint exceder o limite, uma mensagem será retornada indicando que o tamanho máximo foi excedido, juntamente com o código de status 413 e a seguinte mensagem:

```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) é um mecanismo que permite informar ao navegador quais origens têm permissão para fazer solicitações. Este parâmetro define o CORS especificamente para o pipeline e suas restrições. Para configurar isso de forma global e não individualmente para cada pipeline, consulte o artigo [Cabeçalho HTTP CORS](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/platform-administration/governance/policies/transformation/cors-http-header).

Você pode usar uma vírgula para inserir vários valores em um header, mas não deve inserir um espaço antes ou depois da vírgula. Além disso, nenhum caractere especial deve ser utilizado nas chaves, pois isso pode causar erros em proxies e gateways.

</details>

<details>

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

Você pode habilitar as opções **External API** e **Internal API** juntamente com a **mTLS enabled API**, mas recomendamos deixá-las desativadas. Este parâmetro não suporta **API Key**, **Token JWT** ou **Basic Auth**.

Para utilizar esse recurso no seu ambiente, é necessário fazer uma solicitação pelo suporte, e enviaremos as informações necessárias para a instalação deste serviço.

</details>

<details>

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

Ao criar APIs, é comum limitar o número de solicitações que os usuários podem fazer em um determinado intervalo de tempo.

Você pode fazer isso habilitando a opção **Rate Limit** e aplicando as seguintes configurações:

* **Limit:** API
* **Aggregate by:** Credential (API Key, Basic Auth)
* **Options:**
  * **Item 1:**
    * **Interval:** segundo
    * **Limit:** 100
  * **Item 2:**
    * **Interval:** minuto
    * **Limit:** 1000
  * **Item 3:**
    * **Interval:** hora
    * **Limit:** 5000

Se a API tiver caminhos adicionais, o limite será compartilhado entre todos eles. Para aplicar as configurações de limite de taxa, a API deve ser configurada com uma **API Key** ou **Basic Auth**. Dessa forma, o parâmetro **Aggregate by** pode ser usado para grupos de credenciais se a opção **Consumer** for selecionada, ou para uma única credencial se a opção **Credential (API Key, Basic Auth)** for selecionada.

Se vários parâmetros de intervalo com valores repetidos forem configurados, apenas um desses valores será levado em consideração. Também é necessário especificar um valor maior que zero para o parâmetro **Limit**.

Se as opções de limite de taxa não forem configuradas corretamente, elas serão ignoradas e um log de aviso será emitido. Você pode visualizar esse log na página de [**Pipeline Logs**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/dashboards/pipeline-logs).

</details>