Integrações de API

No módulo Studio, na área de Serviços você encontra a aba “Integrações de API”, nessa área, você poderá cadastrar APIs com o objetivo de comunicar com as APIs externas, acessando assim informações de ambientes externos. É importante ressaltar que nessa área é configurada a interface de chamada de serviço, porém, para o funcionamento desse recurso é necessário configurar o modelo de processo, incluindo esse serviço. Para acessar essa área, selecione Serviços e clique na aba “Integrações de API”.

Na aba “Integrações de API” você encontra duas áreas a de “APIs” que apresentam todas as APIs cadastradas na plataforma e o botão “Novo” para cadastro de uma nova API. Outra área que podemos visualizar nessa aba é a de cadastro da API, se selecionado “Novo” é o ambiente para configurar a sua API e se clicar sobre a API, você poderá modificar algumas informações, salvar e publicar novamente a API ou criar uma nova versão.

Para cadastrar uma nova API, clique no botão “Novo” localizado ao lado esquerdo da tela, na área de “APIs”. Ao clicar no botão, os campos serão apresentados na tela para serem preenchidos. No campo “Nome” é necessário informar o nome da Integração API, vamos utilizar um exemplo, “Estados brasileiros”. No segundo campo “Tipo de serviços”, devemos escolher qual o método da API, escolher entre “REST” ou “SOAP”. Vale ressaltar que, dependendo da escolha do método, os próximos campos serão compostos de acordo com a necessidade do método escolhido. No nosso exemplo, utilizaremos uma API do tipo “REST”. No campo “URL” devemos informar o endereço do serviço que será chamado.

Em “Método HTTP” devemos escolher uma das opções “GET”, “POST”, “PUT” ou “DELETE”. A opção “GET” é a mais utilizada, serve para ir buscar uma informação. O “POST”, é utilizado quando queremos criar um recurso. O “PUT” é mais utilizado quando queremos guardar um recurso. E “DELETE” utilizado para deletar um recurso especificado. No nosso exemplo, utilizaremos o “GET”. Em “Tipo de autorização”, você tem a opção de escolha de “Nenhum” ou utilizar um protocolo de autenticação “OAuth2.0”, no nosso exemplo a escolha será por “Nenhum”.

Na sequência, podemos configurar os parâmetros de requisição e de resposta de informações. Para isso, temos os campos “Request Input” e “Response Output”.

Em “Request Input” configuramos quais informações devem ser enviadas no chamado do serviço. Encontramos nessa área, quatro diferentes tipos de parâmetros.“Body”, no qual podemos fazer o envio padrão informando o nome do parâmetro, o valor padrão e o tipo de informação. Para realizar o cadastro desses parâmetros basta clicar em “Request Input” e depois em “Body” e clicar no botão “Adicionar Parâmetros”. Um parâmetro será adicionado para o preenchimento das informações.

Caso queira informar uma forma diferente de fazer a requisição por programação, por exemplo, é só marcar no check box “Exibir esquema” e um quadro em branco será aberto para que você possa incluir a programação e fazer de outra maneira a requisição.

Outro tipo de parâmetro que poderá ser configurado é o “Header”, neste caso a configuração é padrão, sendo necessário informar o nome do parâmetro, valor padrão e tipo. Para acessar esse recurso, basta clicar em “Request Input” depois em “Header” e “Adicionar Parâmetro”.

Ainda temos o “Path Variable” como opção de configuração de parâmetro, dessa forma, podemos deixar a chamada da URL mais dinâmica, definindo os parâmetros na URL que serão substituídos por valores reais no momento da chamada. Dessa forma, você inclui a requisição na URL e define esse parâmetro em “Adicionar parâmetro”. Para acessar esse recurso, basta clicar em “Request Input” depois clicar em “Path Variable” e clicar no botão “Adicionar parâmetro” e preencher as informações de nome do parâmetro, valor padrão e tipo.

A última maneira de fazer a requisição é utilizando a “Query String”, com ela conseguimos passar os parâmetros pela URL com o padrão chave e valor já estabelecido pelo protocolo HTTP.

Os parâmetros serão enviados na chamada do serviço e poderão ser configurados, clicando em “Request Input” depois em “Query String” e em “Adicionar parâmetro”. O campo será apresentado para você preencher o nome do parâmetro, o valor padrão e o tipo. Se desejar incluir mais campos, basta clicar novamente em “Adicionar parâmetros” e se desejar excluir algum campo adicionado, basta clicar na última coluna na linha do campo, em um botão com o sinal de menos.

Em “Response Output”, configuramos quais as informações que iremos receber do serviço, conforme sua estrutura de retorno.

Você poderá mapear as informações de seu interesse, escolhendo uma ou duas informações que gostaria de receber e configurar. Para realizar essa ação, basta clicar em “Response Output” e depois em “Adicionar parâmetros” e preencher o “Nome” com o nome do atributo que queremos como retorno para uso no processo, por exemplo. O “Path”, caminho da informação dentro da estrutura do retorno e o “Tipo” de informação que está sendo mapeada. O campo “Collection ID” receberá o nome da coluna mapeada, onde a collection é a lista que contém as informações que estão sendo mapeadas. E o “Valor Padrão” de retorno, caso o serviço não retorne a informação para a coluna mapeada. Feita essa configuração de acordo com o seu serviço e suas necessidades, você deverá clicar em “Salvar”, você poderá também testar a integração da API.

Para testar se a integração de API está correta e se está retornando o que se espera, basta clicar no botão “Testar API” e depois clicar no botão “Executar teste”.

O resultado do teste da chamada do serviço será mostrado em duas colunas, sendo a primeira o retorno original do serviço chamado, e a segunda o retorno já mapeado com as informações que queremos usar.

É importante verificar se tudo está correto para que você possa “Publicar” essa integração de API.

Para publicar a API, basta clicar no botão de “Publicar” localizado na barra superior da configuração da API. Uma janela de confirmação será apresentada com a mensagem “Deseja realmente publicar a API?” Se clicar em “Cancelar” a janela de confirmação será fechada e a ação cancelada. Se clicar em “Publicar” a API será publicada.

Observe que ao clicar em “Publicar” o status da API será alterado para um ícone diferente, sinalizando que a API já está publicada.

Após a publicação não é possível alterar a interface de chamada da API. Nesse caso, ela deve ser versionada, caso precise de modificações futuras, ou suspensa caso seja descontinuada.

Para versionar uma integração de API, basta você clicar na integração de API que deseja versionar e depois clicar no botão “Versionar”. Uma caixa de confirmação será apresentada na tela com a seguinte mensagem: “Deseja realmente versionar esta api?”. Se clicar em “Cancelar” a janela será fechada e a ação cancelada e se clicar em “Versionar” a API será versionada.

Uma versão nova será criada, é importante destacar que essa versão (V.2) ainda não está publicada, então você poderá fazer as modificações necessárias, clicar em “Salvar” e depois clicar em “Publicar”.

Vale ressaltar que, ao versionar a API, a nova versão (V.2) inicialmente não contém os campos "Response Output", pois eles podem ser alterados durante o versionamento. Para aplicar os campos da versão V.1 na V.2, você deve alternar a visualização da API e retornar para a integração versionada (V.2).

Você ainda tem a opção de excluir uma API que não deseja mais manter no cadastro ou suspender a sua atividade.

Para suspender, basta selecionar a API que deseja suspender, clicando nela e depois clique no botão “Suspender”. Vale ressaltar que a opção de suspender só estará habilitada em APIs publicadas. Uma janela de confirmação será apresentada com a seguinte mensagem: “Deseja realmente suspender a api?”.

Se clicar em “Cancelar”, a janela será fechada e a ação “Cancelada” e se você clicar em “Suspender” a API ficará suspensa. É importante a informação, que após a suspensão, a API não será mais apresentada para novas integrações, porém, continuará funcionando em implementações realizadas anteriormente.

Após a suspensão da API, um ícone de cadeado será apresentado no status, informando que a API foi suspensa.

É importante ressaltar que todas as APIs que foram publicadas não serão mais excluídas, apenas as APIs salvas mas não publicadas. A opção de excluir é desabilitada, principalmente, para garantir que processos que utilizem essas APIs não possam ser prejudicados com sua exclusão. Dessa forma, para excluir uma API que não tenha sido publicada ainda, basta selecionar a API, clicando sobre ela e depois clicar no botão “Excluir”, uma janela com a confirmação da exclusão será apresentada. Se clicar em “Cancelar”, a janela será fechada e a ação cancelada e se clicar em “Excluir” a API será excluída com sucesso.