Como é definido e como funciona o timeout de uma API, recurso ou operação?

O timeout de uma chamada é o tempo total disponível para que uma requisição seja processada e respondida. Quando uma requisição é recebida mas o backend não envia uma resposta dentro do tempo disponível, a chamada é interrompida e o erro 504 é devolvido.

Como o timeout é definido no Sensedia API Management?

O timeout das requisições é definido em mais de um lugar na Plataforma e existe uma hierarquia:

O gateway trabalha com um timeout padrão de 60 segundos.
É possível definir um timeout específico para uma API, recurso e/ou operação. Essa definição pode ser feita por valor em segundos ou por variável de ambiente. Nesse caso, o timeout mais específico sobrescreve o timeout mais genérico, mas o timeout limite do gateway sempre será respeitado.
Exemplo desse funcionamento:

Imagine que você cria uma API com dois recursos: /resource1 e /resource2. Para a API como um todo, você estabelece um timeout de 30 segundos. No recurso /resource1 você estabelece um timeout de 10 segundos para o recurso como um todo, mas também configura um timeout de 40 segundos para a operação POST e um timeout de 20 segundos para a operação GET. Você cria uma outra operação para esse recurso, uma operação PUT, mas não estabelece nenhum timeout específico para ela. No recurso /resource2 você não configura nenhum timeout.

Qual timeout será válido para cada recurso?
O /resource1 tem várias operações: a operação GET seguirá o timeout de 10 segundos que foi configurado e a operação POST o timeout de 40 segundos. Já a PUT não teve nenhum timeout configurado, então ela seguirá os 10 segundos que foram estabelecidos como timeout do recurso.

O /resource2 não teve nenhum timeout configurado. Ele seguirá, portanto, o timeout configurado para a API, que foi de 30 segundos. Todas as operações do recurso seguirão esse timeout, a menos que se configure um outro valor para cada operação em específico.

Configurando valores de timeout

Agora que você já entendeu a herança de timeouts, vale detalharmos onde e como você configura os valores.

Timeout padrão do gateway

O timeout do gateway tem um valor padrão de 60 segundos e não pode ser alterado pelos usuários. O valor de 60 segundos é calculado para ser mais do que suficiente para requisições HTTP e trabalhar com valores maiores pode significar um comprometimento grande de performance.

Por que um timeout elevado compromete a performance?: Para que os gateways sejam escaláveis e confiáveis, trabalhamos com limites de performance que protegem todo o ecossistema de APIs. O timeout é uma das ferramentas que ajuda a proteger o sistema, evitando acúmulo excessivo de requisições a serem processadas ao mesmo tempo (o que chamamos de threads). Se você tem uma API que bate em um backend lento e aumenta o timeout para garantir que o backend seja capaz de responder às requisições, isso gera um aumento de threads. Quando o limite de processamento do gateway é atingido, as requisições entrantes são barradas, mesmo que sejam para APIs que têm um timeout menor. Ou seja, uma boa governança de APIs pede parcimônia quanto ao timeout de todo o seu ecossistema.

Timeout de APIs, recursos e operações

A definição de valores de timeout específicos para uma API, recurso ou operação é feita no fluxo de uma API (APIs API desejada Edit Flows).

Na tela de edição de fluxo, o valor do timeout é inserido na janela API Destination, que é o item 3 da imagem abaixo. Pelos itens 1 e 2 da imagem definimos se a configuração de API Destination que estamos acessando é referente a todos os recursos de uma API ou a um recurso específico (item 1 — campo Resources) e a todas as operações de um recurso ou uma operação específica (item 2 — campo Operations):

Ao abrir a janela API Destination, é possível preencher o campo Timeout com o valor em segundos ou com uma variável de ambiente.

O valor cadastrado será respeitado se for menor ou igual ao timeout do gateway. Se nenhum valor for inserido, o gateway considerará o próximo valor na hierarquia explicada acima.

Quando incluir uma variável de ambiente?

Você pode estabelecer o timeout como uma variável de ambiente. Neste caso, você deve incluir o nome da variável no campo Timeout. O valor em si deve ser estabelecido em Environments ambiente escolhido Environment Variables. Nesse caso, o valor será exclusivo para o ambiente que contém a variável cadastrada.

Quando o timeout é estabelecido por variável de ambiente, é possível:

Incluir a variável em várias APIs/recursos/operações diferentes. Se você quiser substituir o valor de timeout de todos esses objetos ao mesmo tempo, basta modificar o valor da variável no ambiente, sem necessidade de abrir cada objeto para fazer a alteração.
Definir timeouts distintos com base no ambiente de implantação de uma API. Por exemplo, você pode incluir na janela API Destination o timeout como uma variável de nome timeout. Então, pode incluir a variável timeout em dois ambientes diferente — digamos "Env1" e "Env2" — mas em cada ambiente cadastrar um valor diferente (10 segundos para o "Env1" e 20 segundos para o "Env2"). Quando a API estiver implantada no "Env1", seu timeout será de 10 segundos, mas quando estiver implantada no "Env2" será de 20 segundos.

Consulte a documentação sobre variáveis de ambiente.

As mesmas considerações a respeito de performance relacionadas ao timeout do gateway que levantamos acima se aplicam aqui. Sempre que você cadastrar um valor alto de timeout para uma API/recurso/operação, deve ter em mente o comprometimento de performance e maior risco de indisponibilidade de APIs caso o seu backend não consiga responder com rapidez às requisições entrantes.

Thanks for your feedback!

EDIT

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