Environments

Environments

O design de APIs passa por diversas fases deu desenvolvimento até que chegue em um nível de maturidade suficiente para que elas sejam expostas em um ambiente de produção. A utilização de ambientes isolados garante que as práticas de gerenciamento de APIs atravessem as fase de desenvolvimento, controle de qualidade e produção de forma mais segura, eficiente e controlada.

Com a utilização de Environments, as APIs podem ser implantadas em ambientes autônomos, e as partes interessadas têm acesso somente ao seu próprio ambiente. Dessa forma, cada ambiente é independente e pode ter seu próprio ciclo de vida.

Na tela de Environments é possível configurar o InboundURL, que encaminhará as requisições para o backend, podendo este InboundURL estar associado a vários Gateways. Por padrão, dois Environments são criados como exemplo, sendo eles Production e Sandbox, devendo ser alterados posteriormente com valores válidos.

A imagem a seguir ilustra estes dois Environments:

Cadastro de Environments

Para cadastrar um Environment, basta clicar na opção "Create Environment". Nesta área, devem ser preenchidos todos os campos obrigatórios, sendo eles:

  • Name: Nome que indentifica o Environment;

  • Inbound URL: Deve ser inserida a URL que representa este Environment e servirá para receber as requisições realizadas às APIs que forem hospedadas neste Environment;

  • Description: Descrição que ajuda na identificação do Environment.

Mais abaixo, podemos encontrar duas seções: Environment Deployment Permission e Environment Trace Visibility.

A opção Environment Deployment Permission está relacionada a permissão de Deploy de APIs dentro do Environment. Já com a opção de Environment Trace Visibility, conseguimos restringir a visibilidade de acesso à listagem de chamados presentes no Trace para as APIs que foram associadas a este Environment, de acordo com um usuário ou grupo de usuários.

  • Organization: Liberará acesso para todos os usuários logados no sistema.

  • Teams: Habilitará acesso para os Teams incluídos nessa opção. Para saber mais sobre a criação de times, veja Teams.

  • Only me: Permitirá acesso apenas para o login do usuário que criou o Environment.

    • Add users: Autorizará acesso também para os usuários adicionados, conforme mostra a imagem abaixo.

Obs: A opção de Environment Trace Visibility será aplicado no General Trace e também para o Trace especifico de cada Api. Para mais informações, veja General Trace.

Os Environments serão exibidos no cadastro da API ou poderão ser inseridos posteriormente no Overview da API. No cadastro, basta selecionar as URLs e no Overview, será necessário editar os dados cadastrais para inserir as URLs dos Environments, conforme mostram as figuras abaixo:

Environment Variables

Ao trabalhar com APIs faz-se necessário ter configurações diferentes para contextos diferentes. Por exemplo, enviar requisições para um ambiente de Sandbox ou para um ambiente de produção. Os Environments oferecem a capacidade de personalizar requisições utilizando variáveis de ambiente. Desta forma, é possível alternar facilmente entre contextos diferentes utilizando variáveis.

No API Suite é possível criar variáveis de ambiente que podem ser utilizadas nos fluxos das APIs e em alguns Interceptors, como por exemplo o Interceptor de Rate Limit.

Para cadastrar variáveis de ambiente é necessário adicionar um Map, ou importar um Map existente de outro environment.

Para adicionar um Map clique no botão ADD MAP. Uma tela será apresentada conforme a imagem abaixo:

Para importar um Map de outro Environment basta clicar sobre o botão IMPORT MAP. Uma tela será apresentada conforme a imagem a seguir:

Basta começar a digitar o nome do Environment correspondente para o sistema carregar as informações necessárias. Em seguida, selecione o Map desejado e clique em IMPORT MAP.

Logo após, poderão ser criadas as variáveis de ambiente.

Uma variável de ambiente é uma cadeia de caracteres composta por uma chave e um valor. No exemplo abaixo, foram criadas duas variáveis: uma variável denominada destination com um endereço válido, e uma variável denominada rateLimit com o valor 2.

A variável de ambiente $destination pode ser utilizada, por exemplo, como o endpoint de uma API. Dessa forma, quando uma requisição for realizada para a API, o Gateway irá direcionar a chamada para o endereço configurado.

Para isso, basta referenciar a variável de ambiente no Target Destination da API conforme a imagem a seguir:

Observação: Todas as variáveis de ambiente ao serem referenciadas nas APIs ou nos interceptors devem ser precedidas do símbolo $.

Na imagem abaixo, temos um exemplo de utilização da variável de ambiente $rateLimit no interceptor correspondente. Dessa forma, quando for feita uma requisição para a API, o Gateway irá substituir a quantidade de chamadas pelo valor configurado na variável. No caso, o valor = 2.