Flows

O que são fluxos de API?

A arquitetura para exposição de APIs amplamente adotada no mercado prevê a separação de responsabilidades, para a qual a presença de um gateway de APIs como elemento intermediário entre os clientes e o backend é fundamental.

Por padrão, todos os dados de uma requisição (request) são passados sem alterações para o backend pelo roteamento do gateway. O mesmo acontece com a resposta (response) enviada pelo backend. Por padrão, todos os dados da resposta são passados sem alterações para o cliente que originou a requisição.

Contudo, há diversas situações nas quais é necessário ou desejável modificar os dados da requisição antes de enviá-la ao backend, ou alterar a resposta padrão que será devolvida ao cliente. Por exemplo, você pode querer:

adicionar informações à requisição antes de encaminhá-la ao backend (enriquecimento de mensagens);
remover ou mascarar informações sensíveis que não devem ser armazenadas em logs;
tomar decisões de rotas com base no conteúdo das mensagens;
compor mais de uma chamada a serviços internos em uma mesma requisição externa.

A definição de uma API inclui a configuração dos fluxos de entrada e saída das mensagens. No caminho desses fluxos, podem ser adicionados interceptores (ou interceptors, em inglês) em pontos específicos, e eles serão executados em uma ordem bem definida. São esses interceptores que executam as lógicas e estabelecem comportamentos específicos.

A execução dos interceptores segue uma hierarquia em árvore, respeitando a ordem na qual foram configurados.

A imagem abaixo mostra um cenário no qual interceptores são adicionados nos fluxos de entrada e saída das mensagens:

Você pode adicionar interceptores-padrão (que já estão prontos para uso no seu Manager) ou interceptores personalizados aos fluxos de sua API. Acesse aqui para ler sobre os interceptores disponíveis.

Configuring API flows

Na configuração do fluxo, podem ser definidos:

O escopo de execução do fluxo, que engloba:
- Resources: exibe todos os recursos da API. Quando selecionado "All", o fluxo será aplicado em todos os recursos.
- Operations: exibe todas as operações para o recurso selecionado. Segue o mesmo conceito dos recursos: se for selecionado "All", aplica-se a todas as operações de um recurso.
O conjunto de interceptors, que são divididos em: Traffic, Security, Mediation, Tracing, Transformation, Custom.
O ponto de execução da requisição realizada do cliente para o servidor. A ordem dos interceptores — da esquerda para a direita — define como será o processamento. Todos os interceptores são válidos para este ponto de execução.
O ponto de execução da resposta retornada do servidor para o cliente, mediante algum processamento dos interceptores. A ordem dos interceptores segue da direita para a esquerda. Alguns interceptores não fazem parte deste ponto de execução, como Client ID Validation, Access Token Validation e OAuth.
O destination da API, que pode ser definido como o mesmo para todas as chamadas da API ou específico para um determinado recurso ou operação (dependendo de você ter escolhido "All" nos campos de Resource e Operation ou ter definido um recurso/operação específicos). Para configurar o destination, clique no botão , por meio do qual você também define os certificados usados e um timeout específico.
- O timeout determina o tempo limite de espera de consumo de um determinado recurso ou operação. Quando o tempo de uma requisição exceder o valor do timeout configurado, a requisição será abortada e uma exceção será lançada pelo sistema com o status 502.
  - O campo timeout pode ser definido diretamente, com valor em segundos, ou através de uma variável de ambiente.
  - O timeout segue o conceito de hierarquia do mais genérico para o mais específico. Ex.: um timeout definido em "All" será replicado para todos os recursos e operações, a menos que seja definido um timeout diferente em um componente mais específico.

Herança de fluxos

Podemos criar vários fluxos para uma chamada a uma API.

Os fluxos seguem um modelo de hierarquia, ou seja, os interceptores do pai serão herdados pelos seus filhos, mas as modificações nos filhos não serão refletidas no pai.

Os interceptores herdados do pai aparecem em cinza escuro, enquanto os novos interceptores adicionados são coloridos:

Quebras de fluxo

Uma quebra de fluxo acontece quando há alteração na ordem dos interceptors herdados de um fluxo pai. Nesse caso, todas as alterações feitas nos interceptors do fluxo pai não serão repassadas para seus filhos.

O que causa quebras de fluxo:

mudança na ordem dos interceptores herdados do pai;
mudança na ordem dos interceptores do filho, à frente dos interceptores herdados do pai;
mudança na ordem dos interceptores do filho, no meio dos interceptores herdados do pai;
adição de novo interceptor à frente dos interceptores herdados do pai;
adição de novo interceptor no meio dos interceptores herdados do pai.

O que NÃO causa quebras de fluxo:

mudança na ordem dos interceptores do filho depois dos interceptores do pai;
adição de novo interceptor depois dos interceptores herdados do pai;
alteração dos valores dos interceptores do pai.

Os valores alterados no filho serão transmitidos para seus filhos herdeiros; porém, se houver uma alteração no valor do pai, ela não será transmitida para os filhos nem para os filhos herdeiros.

A imagem a seguir representa um fluxo filho normal, no qual os interceptors em cinza são herdados e foi adicionado um interceptor de Log na requisição, obedecendo a ordem dos interceptores.

Abaixo, você pode ver um exemplo de uma quebra de fluxo. A ordem dos interceptors foi alterada: um interceptor de Client ID Validation foi adicionado antes do primeiro interceptor herdado do fluxo pai (Rate Limit). Portanto, qualquer alteração feita no fluxo pai não será refletida no fluxo em questão.

É possível reverter a quebra de fluxo clicando no botão Restore, localizado ao lado do campo de seleção de Operations.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]