API

Você não entra na cozinha: faz o pedido no balcão

Pense num restaurante. Você tem fome, a cozinha tem a comida, e você não pode entrar lá. O garçom leva o pedido e traz o prato. Numa automação, você é o sistema que pede, a cozinha é o servidor da outra empresa (o computador onde o sistema dela roda), e o garçom é a API. Siga um pedido do começo ao fim.

Você não precisa saber cozinhar. Precisa saber pedir do jeito que o cardápio aceita, e ler o que volta.

Cinco palavras leem quase toda documentação

Pense na comanda: se faltar a mesa ou o prato, ela volta da cozinha sem ser atendida. O garçom só entende pedido no formato fixo que a documentação (o manual que o serviço publica dizendo como pedir) descreve: pedido confuso, cozinha não entende, e volta erro. Este é um pedido real no formato, para uma loja de exemplo que quer os dados do cliente 42. Clique em cada parte.

Toda documentação decente mostra três coisas para cada operação: o endereço, o que ele aceita e como é a resposta. Procure primeiro a seção de início rápido, depois a de autenticação (como provar quem você é), depois o limite de pedidos.

O conector pronto da sua ferramenta (o bloco com o logotipo do serviço, em que você só escolhe a conta e preenche campos) é este mesmo pedido, já embrulhado: alguém montou o endereço, o verbo e o cabeçalho, e deixou para você só os campos. Veja a mesma tarefa, criar um item numa lista de tarefas, escrita de três jeitos.

A ordem de escolha: primeiro o conector pronto; se não houver, o pedido à mão, que a documentação quase sempre traz de exemplo. Por isso a pergunta “dá para a minha automação falar com tal sistema?” tem resposta curta: se ele publica a documentação da API, dá.

Buscar, criar, mudar, apagar

No restaurante, todo pedido ao garçom é um de quatro: ver o que tem, pedir um prato, trocar o que veio ou cancelar. O verbo diz o que você quer que a cozinha faça. São quatro, e buscar e criar resolvem a maior parte do dia a dia. Troque o verbo e veja o que acontece com a tabela de clientes do outro lado.

O verbo não é intercambiável. Se a documentação diz buscar e você manda criar, a cozinha recusa com um número que quer dizer "esse verbo não serve aqui".

Trabalho que demora (gerar um vídeo, transcrever uma gravação) usa dois verbos: POST começa o trabalho, e GET, mais tarde, busca o resultado pelo número do pedido que voltou no primeiro.

Monte o pedido e veja o que a cozinha responde

Antes de levar convidados a um restaurante novo, vale testar a casa: pedir errado de propósito e ver o que o garçom responde. A loja de exemplo tem um cardápio pequeno: clientes, e um cliente pelo número. Monte o pedido, envie e leia o número antes de ler o resto. Tente tirar a credencial, pedir o cliente 999 ou mandar cinquenta pedidos de uma vez.

Quando o serviço responde 429 (“devagar”: você mandou pedidos demais por minuto), a saída é uma repetição com pausa: o fluxo manda um item por vez e espera alguns segundos entre um pedido e outro. Mas a pausa só entra quando o outro lado limita. Para ir um item por vez você não precisa dela: o passo já roda uma vez para cada item da lista, sozinho, como mostra tudo chega em lista. Pausa posta “para garantir” só deixa o fluxo mais lento. Quando o limite existe, faça a conta da fila.

Leia o número antes de mexer em qualquer coisa

Quando o prato não vem, o garçom diz por quê: “esse prato não está no cardápio” é problema de quem pediu; “a cozinha parou” é da casa. O erro mais caro não é o erro: é ver o aviso vermelho e refazer tudo sem ler o número. Cada número aponta para um lugar diferente. Diga o que você confere primeiro em cada caso.

Credencial: como a cozinha sabe que é você

Pense no restaurante da empresa: o garçom só anota o pedido de quem mostra o crachá. Credencial é esse crachá, com o seu nome e a assinatura da empresa. A cada pedido, o seu sistema mostra o crachá; a cozinha confere e libera. Sem o crachá certo, volta 401, que não é defeito: é a porta fechada. Quatro tipos cobrem quase todos os serviços.

Dê nome a cada credencial: serviço, conta e para quê (“Planilhas · conta do financeiro”). Com três, você lembra qual é qual; com dezenas, o nome é o único jeito de saber o que revogar quando alguém sai.

Pedir é uma direção; ser avisado é a outra

É a diferença entre ir ao balcão perguntar se o prato já saiu e ouvir a campainha tocar quando ele fica pronto. Tudo nesta página é você indo buscar: o seu sistema chama o garçom. Existe a direção contrária, em que o outro sistema toca a sua campainha quando algo acontece. A maior parte das automações usa as duas.

O par mais comum: o aviso chega curto ("o pedido 781 foi pago"), e o seu sistema usa a API para buscar o pedido completo. O que vem dentro do aviso e da resposta está escrito num formato só, explicado na página JSON.

Três ideias

Papel: alguém que liga sistemas entre si e explica para quem não é da área.
Contexto: quero que [a minha automação / a minha planilha] faça [o quê, por exemplo: buscar os pedidos do dia] usando a API de [nome do serviço]. Vou colar abaixo o trecho da documentação.
Tarefa: me diga o endereço, o verbo, o que vai no cabeçalho, o que vai no corpo, que tipo de credencial ela pede e qual o limite de pedidos.
Formato: uma tabela com essas seis linhas. Depois, o pedido de exemplo pronto, com sua-chave-aqui no lugar da chave.
Limitações: use só o que está no trecho. Se algo não estiver escrito, diga "não está na documentação" em vez de supor. Nunca me peça a chave de verdade.
Critério de sucesso: eu monto o pedido na minha ferramenta sem voltar à documentação.

[cole aqui o trecho da documentação]

API

O balcão por onde um sistema faz pedidos a outro, com formato e regras combinados.

Endereço (endpoint)

O endereço de uma operação. Não é o site da empresa: é um endereço próprio, como api.loja-exemplo.com/clientes.

Verbo (método)

O que você quer que aconteça: GET busca, POST cria, PUT ou PATCH mudam, DELETE apaga.

Cabeçalho (header)

A etiqueta do pedido: quem é você e em que formato está mandando.

Corpo (body)

O conteúdo do pedido, quando você cria ou muda algo.

Código de resposta (status)

O número que volta resumindo o que aconteceu: 2 deu certo, 4 problema no pedido, 5 problema do outro lado.

Credencial

O crachá que prova que o pedido é seu e que você tem permissão.

OAuth

A credencial em que você entra com a sua conta numa janela e autoriza o que o sistema pode fazer.

Limite de pedidos (rate limit)

Quantos pedidos o serviço aceita por minuto ou por dia. Passou, volta 429.

Conector pronto

O bloco da ferramenta com o nome do serviço: o mesmo pedido de API, já montado, com só os campos para preencher.

Repetição com pausa

O fluxo manda um item por vez, com uma espera entre um pedido e outro. É a saída quando o outro lado limita o ritmo.

Simplificação didática. A loja, os clientes e as respostas do simulador são fictícios; serviços reais variam nos nomes e nos detalhes, e o mesmo número às vezes vem com explicações diferentes. A analogia do restaurante explica a direção dos pedidos, não como um servidor funciona por dentro. A lista de tarefas e os números da fila também são de exemplo; os limites de verdade estão na documentação de cada serviço.