Flows

Essa página mostra a versão mais recente do produto (a partir da 4.3.4.x+). Para versões anteriores, acesse este link.

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);

  • recuperar informações específicas (para identificar a origem da requisição, por exemplo);

  • 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:

flow all interceptor

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:

  1. 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. flow resource interceptor

    • 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. flow operation interceptor

  2. O conjunto de interceptors, que são divididos em: Traffic, Security, Mediation, Tracing, Transformation, Custom.

  3. 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.

  4. 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.

  5. 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 icon backend, 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.

flow destination

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:

flow parent child

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.

interceptors natural order

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.

flow break

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

flow break restore

Alertas e dúvidas comuns sobre fluxos

  • Às vezes, você pode tentar encontrar um interceptor para inserir no fluxo e ele parece estar faltando. Nesses casos, é interessante checar se o interceptor pode ser usado para o escopo que você selecionou (API como um todo, nível de recurso ou operação).

  • Há interceptores que podem ser adicionados tanto ao fluxo de requisição quanto ao de resposta, mas há outros que só podem ser arrastados a um dos fluxos. Você pode checar a documentação específica do interceptor que quer configurar para mais detalhes.

  • A ordem dos interceptores no fluxo reflete a ordem com que cada um será aplicado na chamada. Leve isso em consideração quando arrastar interceptores ao fluxo. Quando uma chamada estiver completa, você pode checar a sequência de execução de interceptores nos detalhes do Trace (em General Trace  chamada desejada  aba GATEWAY TRACE).

  • Quando você quiser editar o fluxo de uma API, não basta salvar as modificações na tela de edição do fluxo. Quando você for redirecionado à tela de Overview da API, é preciso salvar a própria API.

  • Só é possível identificar a app de uma chamada se for adicionado um interceptor que valide client ID no fluxo (OAuth ou Client ID Validation). Além disso, a app deve estar associada à API por meio de um plano.

Veja mais dúvidas frequentes sobre fluxos de APIs (e tudo o mais) na nossa seção de FAQs da API Platform.
Thanks for your feedback!
EDIT

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