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 é abortada e o erro 504 é devolvido.

Como o timeout é definido na Sensedia API Platform?

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 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 GET seguirá o timeout de 10 segundos que foi configurado e a 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 mas 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.

Veja mais sobre variáveis de ambiente aqui.

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]