API

O bloco API faz uma requisição HTTP a uma URL e devolve a resposta. Use-o para chamar qualquer API REST: buscar dados, criar um registro ou acionar um endpoint externo.

Configuração

URL

O endpoint a chamar. Digite uma URL estática, ou insira uma connection tag para montá-la a partir de uma saída anterior, como https://api.example.com/users/<start.userId>.

Method

O método HTTP: GET, POST, PUT, DELETE ou PATCH. O padrão é GET.

Query Params

Pares chave-valor anexados à URL como query string. apiKey e limit viram ?apiKey=…&limit=10.

Headers

Headers de requisição em pares chave-valor, como Content-Type: application/json ou Authorization: Bearer <secret>. Headers padrão como User-Agent e Accept são adicionados automaticamente, e seus valores têm prioridade sobre eles.

Body

O payload da requisição para POST, PUT e PATCH, enviado como JSON. Digite direto, ou puxe de uma saída anterior com uma connection tag.

Advanced

  • Timeout (ms). Quanto tempo esperar antes de desistir. O padrão é 300000 (5 minutos), até 600000 (10 minutos).
  • Retries. Número de novas tentativas em timeouts, respostas 429 e erros 5xx. O padrão é 0.
  • Retry delay / Max retry delay (ms). Os limites do backoff exponencial usado entre as tentativas.
  • Retry non-idempotent methods. Desligado por padrão, então POST e PATCH não são repetidos, o que evita escritas duplicadas. Ligue apenas quando repetir a requisição for seguro.
  • Proxy URL. Proxy http:// opcional pelo qual a requisição sai, como um proxy residencial para destinos que bloqueiam IPs de datacenter. O host do proxy precisa ser acessível publicamente, e só o esquema http:// é suportado (um destino https:// continua tunelando por ele com segurança). Mantenha as credenciais do proxy em uma variável de ambiente e referencie-a como {{PROXY_URL}} em vez de digitá-las no campo.

Saídas

Depois que a requisição termina, os blocks seguintes leem o resultado pelo nome:

SaídaO que é
<api.data>O corpo da resposta, parseado como objeto quando é JSON ou devolvido como texto nos outros casos
<api.status>O código de status HTTP, como 200 ou 404
<api.headers>Os headers da resposta, como objeto

Ramifique com base no resultado lendo <api.status> em um bloco Condition.

Exemplo

Um workflow que chama um endpoint HTTP e resume a resposta:

O bloco API monta a URL a partir da entrada do Start, busca os dados, e o Agent lê a resposta como <api.data>.

Boas práticas

  • Mantenha segredos em variáveis de ambiente. Referencie-os com {{VAR}} na URL ou nos headers; nunca deixe chaves fixas no código.
  • Trate as falhas. Leia <api.status> e ramifique com um Condition, ou conecte o caminho de erro para falhas de rede e timeouts.
  • Configure retries para endpoints instáveis. Use as configurações de retry em Advanced para chamadas idempotentes. Deixe POST e PATCH desligados, a não ser que repetir a requisição seja seguro.
  • Referencie apenas o campo de que você precisa. Puxe <api.data.id> em vez de todo o <api.data> quando a resposta for grande.

Common Questions

O timeout padrão é de 300.000 milissegundos (5 minutos). Você pode configurá-lo até no máximo 600.000 milissegundos (10 minutos) nas configurações Advanced do block.
As tentativas acontecem em falhas de rede e conexão, timeouts, respostas de limite de taxa (HTTP 429) e erros de servidor (5xx). Erros de cliente como 400 ou 404 não são repetidos.
As tentativas usam backoff exponencial a partir do retry delay configurado (padrão de 500ms). Cada nova tentativa dobra o intervalo, até o máximo do retry delay (padrão de 30.000ms).
Não. POST e PATCH não são idempotentes, então as tentativas ficam desativadas para eles por padrão, para evitar a criação de recursos duplicados. Você pode ativar as tentativas com o toggle 'Retry non-idempotent methods' nas configurações Advanced, mas saiba que isso pode causar requisições duplicadas.
Headers padrão como User-Agent, Accept e Cache-Control são adicionados automaticamente. Qualquer header personalizado que você configurar é mesclado com esses padrões, e seus valores têm prioridade sobre os headers automáticos de mesmo nome.
Pela interface, o block envia corpos de requisição em JSON. A tool HTTP por baixo também suporta form data: se você passar parâmetros de form-data, ela monta uma requisição multipart/form-data automaticamente. Para a maioria dos casos, o campo de body JSON é suficiente.
AgentFunction