Desenvolvimento Rápido de APIs Rest usando ferramentas do InterSystems Open Exchange

Neste artigo, vou compartilhar o tema que apresentamos no Global Summit 2023, na sessão Tech Exchange. Eu e @Rochael Ribeiro.

Nesta oportunidade, abordamos os seguintes tópicos, os quais iremos explorar neste artigo:

• Ferramentas Open Exchange para o desenvolvimento rápido de APIs
• Open Api Specification (OAS)
• Maneira Tradicional versus Desenvolvimento Rápido
• API Composta (Interoperabilidade)
• Abordagens Spec-First ou Api-First
• Governança e Monitoramento de Api's
• Demonstração (vídeo)

Ferramentas Open Exchange para o Desenvolvimento Rápido de APIs Rest

Como estamos falando de desenvolvimento rápido de APIs modernas (Rest / json) vamos utilizar duas ferramentas do Intersystems Open Exchange:

A primeira é um framework para desenvolvimento rápido de APIs a qual iremos detalhar neste artigo.

https://openexchange.intersystems.com/package/IRIS-apiPub

A segunda é para utilizarmos o Swagger como interface de visualização da especificação e documentação das APIs Rest desenvolvidas na plataforma IRIS, bem como a sua utilização/execução. A base para o seu funcionamento é o padrão Open Api specification (OAS), descrito a seguir:

 https://openexchange.intersystems.com/package/iris-web-swagger-ui

O que é Open API Specification (OAS)?

É um padrão utilizado mundialmente para definir, documentar e consumir APIs. Na maioria dos casos, as APIs são desenhadas antes mesmo da sua implementação. Vamos falar mais sobre isso nos próximos tópicos.

Mas este padrão também serve para agilizar testes e chamadas das APIs em ferramentas (Rest Apis Clients) de mercado, como o Swagger, Postman, Insomnia, etc… 

Forma tradicional de publicação de uma API usando o Intersystems IRIS

Imagine que queremos publicar uma API com base em um método IRIS já existente (figura abaixo).

No método tradicional:

1: Temos que pensar em como os consumidores irão chamá-la. Por exemplo: Qual path e verbo iremos utilizar e como iremos responder. Se em um objeto JSON ou como um plain/text.

2: Vamos ter que construir um novo método em uma classe %CSP.REST que irá manipular a chamada http e irá fazer uma chamada para este método.

3: Vamos manipular a resposta do método para a resposta http planejada para o usuário final.

4: Teremos que pensar em como iremos prover o código de sucesso e como iremos tratar as exceções.

5: Vamos mapear a rota para o nosso novo método.

6: Temos que pensar em como iremos prover a documentação da API para o usuário final. Iremos usar o Open Api Specification?

7: E se por exemplo tivermos um método com um payload de requisição ou resposta, o tempo de implementação de tudo irá aumentar, porque o payload também deverá ser documentado. 

E como podemos ser mais rápidos?

Simplesmente marcando o método IRIS com o atributo [WebMethod], seja ele qual for, que o framework irá cuidar da sua publicação, utilizando-se do padrão OAS 3.x.

E por quê o padrão 3.x é tão importante?

Porque ele também documenta detalhadamente todas as propriedades dos payloads na entrada e saída.

Desta maneira, quaisquer ferramentas Rest Client de mercado podem instantaneamente se acoplar às APIs, como o Insomnia, Postman, Swagger, etc...

Utilizando o Swagger já iremos visualizar a nossa API (acima) e já podemos chamá-la.

Customização da API

Mas e se eu precisar customizar a minha API?

Por exemplo: Ao invés do nome do método eu quero que o path seja outro. E quero que os parâmetros de entrada estejam no path, não somente como um query param.

Definimos uma notação específica acima do método, onde podemos complementar as meta-informações que o método por si só não provê.

Neste exemplo estamos definindo um outro path para a nossa api e complementando as informações para o usuário final ter uma api mais amigável.

Mapa de projeção de método IRIS para API Rest

Este framework suporta inúmeros tipos de parâmetros.

Neste mapa podemos destacar os tipos complexos de parâmetros, ou seja, os objetos. Eles serão expostos automaticamente como um payload JSON e cada propriedade será devidamente documentada para o usuário final.

Interoperabilidade (Apis Compostas)

Suportando tipos complexos, é possível também expor métodos construídos para a Interoperabilidade.

É um cenário propício para a construção de APIs compostas, que se utilizam de orquestração de múltiplos componentes externos (outbounds).

Isso significa que os objetos ou mensagens utilizadas como request ou response serão automaticamente publicadas e interpretadas por ferramentas como o swagger.

E é uma forma excelente para testar componentes da interoperabilidade, pois geralmente um template do payload já é carregado para que o usuário saiba quais propriedades a API se utiliza.

Primeiro o desenvolvedor pode focar no teste, depois pode fazer o refinamento e customizar a exposição da API Rest.

Abordagem Spec-first ou Api-first

Outro conceito amplamente utilizado atualmente é ter a definição da API antes mesmo de sua implementação.

Com este framework é possível fazer a importação de uma especificação (OAS) para uma classe com a estrutura (spec) dos métodos já definidos, faltando apenas a sua implementação. 

Governança e Monitoramento de Apis

Para a governança das APIs, é igualmente recomendada a utilização do IAM em conjunto com o apiPub.

Além de ter múltiplos plugins, o IAM pode se acoplar rapidamente às APIs através do padrão OAS.

O apiPub oferece um tracing adicional para as APIs que será demonstrado a seguir.

Demonstração

https://www.youtube.com/embed/IdJ1PqmhH3c
[Isso é um link incorporado, mas você não pode ver conteúdo incorporado diretamente no site, porque recusou os cookies necessários para acessá-lo. Para ver o conteúdo incorporado, você precisa aceitar todos os cookies nas suas Definições de cookies]

Download & Documentação

Intersystems Open Exchange: https://openexchange.intersystems.com/?search=apiPub

Documentação Completa: https://github.com/devecchijr/apiPub