Experiência e feedback do curso on-line "Hands-On with InterSystems API Manager for Developers" 

Com o meu conhecimento básico sobre o contêiner Docker e a API REST, queria tentar usar o InterSystems API Manager pela primeira vez para controlar APIs e microsserviços. Concluí esse curso online usando minha instância IRIS local como host (SO Windows) e o IAM em execução em uma VM Linux (convidado). 

Primeiro, quero apresentar o InterSystems API Manager (IAM), explicar as etapas para configurar meu ambiente local e, por último, mostrar os capítulos do curso.

Introdução

Atualmente, o gerenciamento de API é muito importante ao aproveitar as vantagens da fácil implantação, com um portal de IU centralizado para gestão, monitoramento e proteção do tráfego da API.

O InterSystems API Manager (IAM) controla APIs e microsserviços consumidos e expostos pelo aplicativo IRIS. É um gateway de API entre sistemas downstream e upstream e também tem uma maneira de rastreamento visual para descobrir como as APIs são chamadas, com que frequência elas são chamadas e quem as chamam. 

Benefícios de usar o IAM:

• Monitorar APIs baseadas em HTTP
• Controlar o tráfego 
• Proteger a API usando o mecanismo de segurança 
• Facilidade de uso para um novo desenvolvedor em processo de integração

Configuração do IAM

O que eu instalei antes de começar a configurar o IAM

• Windows (instância do IRIS instalada)
• VM Linux (Docker instalado)

Ative a instância InterSystems IRIS para o usar o IAM

1. Abra o Portal de Gerenciamento da instância IRIS e ative o IAM.

   1. No Portal de Gerenciamento, selecione System Administration > Security > Users e selecione o usuário IAM
   2. Clique no botão de opção Password 
   3. Insira e confirme uma senha para o usuário IAM
   4. Selecione a caixa User enabled 
   5. Selecione Save

2. Ative o aplicativo da Web IAM (confira se a sua licença do IRIS especifica "gerenciamento de API") 

   1. No Portal de Gerenciamento, selecione System Administration > Security > Applications > Web Applications e selecione o "/api/iam" 
   2. Selecione a caixa Enable Application 
   3. Selecione Save

Faça o download e extraia os arquivos de instalação do IAM

1. Faça o download do kit de instalação do IAM da WRC dentro do ambiente Linux
2. Extraia os arquivos tar (Não extraia iam-image.tar, porque essa é a imagem docker do IAM)

Configure e inicialize o IAM 

Nessa etapa, usei o usuário ROOT já que eu estava obtendo erros como "Não foi possível carregar o Portal de Gerenciamento corretamente" ou o script de configuração não estava transmitindo o valor das variáveis de ambiente para o arquivo docker-compose.yaml quando eu usei o sudo com meu usuário Linux. Uma solução para o último problema foi usar "sudo -E" para transmitir as variáveis de ambiente.

1. Abra o terminal executando o comando "docker load -i iam_image.tar" no diretório onde você extraiu o arquivo do IAM.
2. Execute "source ./scripts/iam-setup.sh" no diretório atual ou "source ./iam-setup.sh" na pasta "scripts".
   1. Insira o nome exato da imagem do IAM e o nome do repositório de https://containers.intersystems.com/contents Por exemplo: intersystems/iam:3.0.2.0-2 (Essa etapa é obrigatória. Caso contrário, você receberá um erro sobre a falha na autenticação do repositório após executar o "docker compose")
   2. Insira o endereço IP exato da máquina host (Você pode encontrar a especificação IPV4 na configuração do Windows, não insira localhost ou 127.0.0.1)  
   3. Insira o número da porta da instância IRIS no SO do Windows, por exemplo 52773 
   4. Insira e confirme a senha do usuário IAM
3. Dentro do diretório "scripts", execute "iam-test.sh" para testar a conexão
4. Dentro do diretório "scripts", execute "docker compose up -d" para inicializar o IAM
5. Inicialize o portal do IAM no Linux ao acessar: http://localhost:8002/overview

Se você não conseguir dar um ping no endereço host usando a VM, confira Firewall do Windows - Configurações Avançadas - Regras de Entrada. Habilite  Ativar compartilhamento de arquivos e impressoras (Solicitação de Echo - ICMPv4-In) Perfil: Privado, Público

Teste o IAM

Dentro do kit de instalação, você encontrará um script chamado "iam-test.sh" no diretório de scripts. 

Digite e execute "./iam-test.sh" para começar a testar a conexão entre o IAM e a instância IRIS. 

Observação: se o resultado do teste disser "Error creating service. HTTP Status Code:000 ou Error creating service. HTTP Status Code:409" (Erro ao criar o serviço. Código de Status HTTP:000 ou 409), confira o status do docker. Se estiver íntegro, mas ainda não funcionar, encerre o contêiner e execute o docker compose novamente. Pela minha experiência, isso pode acontecer após você pausar a VM.

Para saber mais, encontre aqui a documentação de configuração do IAM: https://docs.intersystems.com/components/csp/docbook/DocBook.UI.Page.cls?KEY=CIAM3.0_install#CIAM3.0_install_setupIAM

Exercício prático: https://learning.intersystems.com/course/view.php?name=IAMExercise

 

Capítulos do curso

Depois de fazer esse exercício, concluí os três capítulos principais que eu gostaria de compartilhar:

• Configuração de Serviços
• Configuração de Rotas
• Configurações de Consumidores e Plugins

Antes de começar a usar o IAM, esse exercício pediu que eu criasse uma solicitação REST usando o método GET, essa solicitação HTTP é do servidor cliente e aponta diretamente para o endpoint, que é um aplicativo da Web criado com base em uma instância IRIS. 

Para as próximas etapas, esse exercício mostrou como configurar os serviços a que a solicitação API é encaminhada e a rota que analisa a solicitação de entrada e depois aloca para a API mais adequada.

 

Configuração de Serviços e Roteadores

O que é um serviço? 

Um serviço é configurado para conectar a API Manager ao InterSystems IRIS. Geralmente, você tem um serviço por serviço REST ou aplicativo da Web no InterSystems IRIS. Por exemplo, se você tiver um aplicativo da Web com o caminho base /rest/coffeemakerapp, você configurará um serviço na API Manager para esse URL. Os serviços são geralmente definidos antes das rotas.

O que é uma rota?

Uma rota define o que será chamado pelos aplicativos clientes para o InterSystems API Manager. Geralmente, o serviço é definido antes de uma rota, porque a interface permite que você crie com facilidade as rotas correspondentes diretamente de um serviço definido. As rotas são normalmente versões simplificadas de caminhos no InterSystems IRIS. No exemplo a seguir, você criará rotas para /test, /coffeemakers, /coffeemaker e /newcoffeemaker. Quanto mais específicas forem suas rotas, maior controle você terá sobre suas APIs no API Manager, tanto para visualizar métricas quanto para adicionar plugins a rotas específicas.

Crie um serviço:

1. Acesse o Portal de Administrador do IAM e selecione a guia Services
2. Clique em New Service e nomeie o serviço
3. Selecione Add using URL
4. Forneça o URL base, que é o caminho de URL exato especificado no aplicativo da Web, e confira novamente se o endereço IP da instância está correto (não use localhost nem 127.0.0.1)

Crie uma rota:

1. Role a tela para baixo no resumo do serviço e clique em Add a Route
2. Especifique o nome, os protocolos e o(s) caminho(s)
3. O campo Service deve ser gerado automaticamente com os detalhes do serviço
4. De acordo com o exercício, era necessário desmarcar Strip Path em Advanced Fields. Caso contrário, o caminho seria removido ao enviar a solicitação para o InterSystems IRIS, o que é um elemento importante para a conexão ao endpoint do InterSystems IRIS.

Após criar o serviço e a rota, você pode usar um cliente REST como o Postman para enviar uma solicitação diretamente para o IAM e receber uma resposta "200 ok", por exemplo: GET http://10.0.0.1:8000/test (/test é a rota criada).

Observação: no meu caso, o URL da solicitação HTTP deve corresponder ao endereço IP da VM Linux. Você pode encontrar o endereço IP por Settings-Network ou executar o comando "ifconfig" no terminal. 

Abra o Portal de Administrador do IAM, você verá que a solicitação para mostrar todos os coffeemakers foi registrada com êxito, do cliente REST para o IAM.

Até mesmo com as solicitações CRUD básicas, em vez de enviar a solicitação HTTP diretamente para o aplicativo da Web do IRIS, o uso do IAM proporciona uma representação visual para controlar as APIs e manter a segurança do endpoint.

Usando plugins

Um dos benefícios de usar o IAM é que há vários plugins disponíveis, como o plugin de limitação de taxa, para ajudar com o throttling, de ACL e de OAuth2.0. No meu caso, vou compartilhar minha experiência ativando basic-auth e criando um consumidor.

Ative o plugin basic-auth

1. Acesse o Portal de Administrador do IAM e selecione a guia Plugins
2. Clique em New Plugin > Basic Authentication > Create

Crie um usuário IRIS para a autenticação básica 

1. Abra o Portal de Gerenciamento do IRIS 
2. Acesse System Administration > Security > Users > Create New User
3. Defina um nome de usuário e senha
4. Deixe os outros campos em branco e clique em Save. No meu caso, criei um usuário chamado "CoffeeManager"

Crie um consumidor e configure as credenciais

1. Acesse o Portal de Administrador do IAM e selecione a guia Consumers
2. Clique em New Consumer > Insira CoffeeManger (no meu caso) em Username > Create
3. Acesse a página de informações do CoffeeManager > Credentials > New Basic Auth Credential
4. Use as credenciais do usuário que criamos na instância IRIS > Salve

Agora concluímos todos os requisitos para o plugin basic-auth funcionar

Envie uma solicitação HTTP usando a autenticação básica com a credencial "CoffeeManager" que criamos na última etapa 

Acesse a página de informações do CoffeeManager > Activity, você verá que uma solicitação foi registrada

Conclusão

Em suma, comecei apresentando o que é o InterSystems API Manager (IAM) e seus benefícios. Expliquei como configurar o IAM em uma VM Linux e como usar o IAM ao implementar suas funções básicas, criar serviços e rotas e ativar plugins e consumidores.

Se você tiver dúvidas e comentários, não hesite em entrar em contato.

Divirta-se e aproveite o IAM!