Chamar API

1. Geral

O passo de ação "Chamar API" permite que os usuários executem chamadas HTTP REST utilizando dados dinâmicos obtidos a partir das views configuradas no Mitra. Cada linha gerada na view representa uma chamada de API, onde as variáveis configuradas no body, headers ou URL serão substituídas pelos valores correspondentes da linha. Caso uma view não seja configurada, será executada uma única chamada, sem a utilização de variáveis.

2. Funcionamento

• Configuração da View (Opcional): O usuário pode configurar uma view utilizando SQL, para selecionar os dados que deseja utilizar nas chamadas de API. Cada coluna da view se torna uma variável disponível para ser utilizada na configuração da chamada de API. Se nenhuma view for configurada, a chamada será realizada uma única vez, sem a utilização de variáveis.

• Uso das Variáveis: As variáveis das colunas podem ser utilizadas no body, headers ou URL da chamada de API, utilizando o formato $nome_da_variavel, onde nome_da_variavel é o nome da coluna da view, sempre em letras minúsculas. 

  • Exemplo: Para uma coluna chamada ID_CLIENTE, a variável será $id_cliente.

• Body Personalizado:

  • Com Body Personalizado: Se o usuário ativar a opção "Habilitar body personalizado", ele pode criar um corpo de requisição customizado, utilizando as variáveis da view.

  • Sem Body Personalizado: Caso a opção não seja ativada, o body padrão será gerado automaticamente com base nos campos e valores retornados pela view, seguindo o formato JSON.

• Execução: Para cada linha retornada pela view, será realizada uma nova chamada de API, substituindo as variáveis pelos valores correspondentes da linha. Se não houver view configurada, apenas uma chamada será realizada com o body padrão ou personalizado.

• Registro de Logs: Todas as chamadas realizadas são registradas na tabela INT_HTTP_REQUEST_LOG, permitindo que o usuário acompanhe o status e resultado de cada chamada.

3. Estrutura de Configuração

3.1. Tipo de Chamada

• GET: Recupera informações de um endpoint.

• POST: Cria um novo registro no endpoint.

• PUT: Atualiza um registro existente.

• DELETE: Remove um registro existente.

3.2. URL

Informe a URL do endpoint que deseja chamar. Exemplo:

3.3. Headers

Adicione os headers necessários para a autenticação e formatação da requisição. Exemplo:

• Content-Type: application/json

• Authorization: Bearer $api_key

3.4. Body

Informe o corpo da requisição no formato JSON. Utilize as variáveis geradas pela view para dinamizar os dados enviados.

• Com Body Personalizado Ativado: Exemplo:

{
  "cliente_id": "$id_cliente",
  "nome": "$nome_cliente",
  "email": "$email_cliente"
}

• Sem Body Personalizado: O body será gerado automaticamente com base nos campos e valores da view. Se a view retornar os seguintes dados:

O body de cada chamada será:

{
  "id_cliente": "1",
  "nome_cliente": "João da Silva",
  "email_cliente": "joao@example.com"
}

{
  "id_cliente": "2",
  "nome_cliente": "Maria Souza",
  "email_cliente": "maria@example.com"
}

3.5. Variáveis Disponíveis

Após configurar a view, todas as colunas retornadas estarão disponíveis como variáveis, com os nomes das colunas convertidos para minúsculas. Utilize o nome exato das colunas prefixadas com $ para utilizá-las na configuração.

Exemplo Prático:

Configuração da View:

SELECT 
  ID AS ID_CLIENTE, 
  NOME AS NOME_CLIENTE, 
  EMAIL AS EMAIL_CLIENTE 
FROM 
  CAD_CLIENTES 
WHERE 
  STATUS = 'ATIVO'

Configuração da Chamada de API:

• Tipo de Chamada: POST

• URL: https://api.exemplo.com/v1/clientes

• Headers:

  • Content-Type: application/json

  • Authorization: Bearer $api_key

• Body (Com Body Personalizado Ativado):

{
  "id": "$id_cliente",
  "nome": "$nome_cliente",
  "email": "$email_cliente"
}

3.6. Logs de Requisição

Todos os logs de chamadas serão armazenados na tabela INT_HTTP_REQUEST_LOG, contendo informações como:

• ID: Identificador único do log.

• DHREQUEST: Data e hora da requisição.

• DHRESPONSE: Data e hora da resposta.

• REQUESTBODY: Corpo da requisição enviada.

• RESPONSEBODY: Corpo da resposta recebida.

• HTTPSTATUSCODE: Código de status HTTP retornado.

• STATUS: Status da execução da chamada (CONCLUÍDO, ERRO, etc.).

4. Considerações Finais

• Tratamento de Erros: Sempre verifique o status das chamadas nas tabelas de log para identificar possíveis erros e realizar correções nas configurações.

• Segurança: Mantenha as chaves de API e outros dados sensíveis protegidos e configure permissões adequadas para o acesso às views.