Tema: api-design
-
Como usar corretamente os códigos de status HTTP: a primeira bifurcação do cliente
Clientes, caches e agentes decidem só pelo código de status se repetem, recarregam ou desistem: 201/204 para sucesso com e sem corpo, 401 versus 403 para falta de autenticação versus falta de permissão, 409/412/428 para conflitos e pré-condições, 429 e 503 com Retry-After para «mais tarde». Um 200 com objeto de erro engana todos eles.
-
Tipos de erro legíveis por máquina reduzem novas tentativas prejudiciais de agentes
Hipótese: quando uma API devolve tipos de problema estáveis com indicações de nova tentativa, os clientes automatizados repetem menos pedidos não repetíveis e criam menos escritas duplicadas do que com erros apenas em texto livre; propõe-se uma comparação.
-
Recuar como cliente: Retry-After, cabeçalhos RateLimit e orçamentos por host
Como um agente deve reagir a respostas 429 e 503 e a cabeçalhos consultivos de limite de taxa: respeitar o Retry-After à risca, senão recuar de forma exponencial com jitter, ler os campos RateLimit e RateLimit-Policy quando o servidor os envia para ajustar o ritmo antes do limite, manter um orçamento por host e por chave, e nunca repetir uma escrita não idempotente sem chave de idempotência.
-
Como projetar rate limits que protegem o serviço e informam o cliente
Limite pela identidade que você consegue verificar (conta, prefixo de rede), use contadores atômicos em janelas fixas ou deslizantes, responda com 429 e Retry-After, mantenha orçamentos separados para leituras, escritas e registros e publique os limites efetivos.
-
Paginação e chaves de idempotência na API da Stripe: starting_after, has_more e a janela de 24 horas
Os endpoints de listagem da v1 da Stripe paginam com os parâmetros de cursor mutuamente exclusivos starting_after/ending_before (limit de 1 a 100, padrão 10) e o indicador has_more, e as bibliotecas cliente trazem auxiliares de auto-paginação para percorrer todas as páginas. Requisições POST podem levar uma Idempotency-Key, cujo resultado salvo a Stripe reproduz por cerca de 24 horas, depois das quais as chaves podem ser removidas. Requisições barradas pelo limite de taxa recebem 429 com o cabeçalho Stripe-Rate-Limited-Reason.
-
Nomes e capitalização consistentes nos campos JSON
Escolha uma única convenção de capitalização para os nomes de propriedades e aplique-a em toda parte: o guia de estilo JSON do Google e o ProtoJSON usam lowerCamelCase, e muitas APIs usam snake_case. Além da capitalização, use nomes significativos, enums como strings, timestamps como strings RFC 3339 e inteiros de 64 bits como strings.
-
A especificação Standard Webhooks versus o cabeçalho HMAC da Shopify e o token de segredo compartilhado do GitLab
A especificação Standard Webhooks define os cabeçalhos webhook-id, webhook-timestamp e webhook-signature, um segredo em base64 com prefixo whsec_ cujos bytes decodificados são a chave HMAC e uma assinatura v1,<base64> sobre "{id}.{timestamp}.{payload}"; os tokens de assinatura do GitLab (GitLab 19.0, disponibilidade geral na 19.1) seguem exatamente esse modelo. A Shopify, por sua vez, envia em X-Shopify-Hmac-SHA256 um HMAC em base64 do corpo bruto, e o X-Gitlab-Token mais antigo do GitLab é apenas um segredo compartilhado, sem HMAC algum.
-
Validando JSON com JSON Schema
O JSON Schema descreve a estrutura permitida de um documento (tipos, chaves obrigatórias, enumerações, formatos, limites) e permite validar entradas em qualquer linguagem antes de processá-las; convém declarar additionalProperties de forma explícita.
-
Projetar operações idempotentes e repetições seguras
Uma operação é idempotente quando executá-la várias vezes tem o mesmo efeito que executá-la uma só vez; a RFC 9110 define isso para os métodos HTTP, e o cabeçalho Idempotency-Key estende a propriedade ao POST. Guarde a chave com impressão digital e resultado, sinalize conflitos com 409 e 422 e apague as chaves após um prazo documentado.
-
Chamando a API TypeSafe a partir de um agente: formato da requisição, erros, novas tentativas e fixação de versão
O contrato documentado de que um agente precisa para chamar o Jev sem camada de chat: POST /v1/systemone com chave Bearer, um estado, o nome do modelo e um mapa de perguntas tipadas; respostas com as mesmas chaves das perguntas mais um bloco usage; os status 401, 422, 429 e 529 com backoff exponencial; aliases que mudam e IDs versionados que não mudam; padrões dos SDKs para novas tentativas e a skill do agente para agentes de programação.
-
Modos dry-run para ações de agentes: mostrar o plano antes da alteração
Dê a toda ferramenta que altera estado um modo que calcula e devolve o plano concreto (quais objetos, quais campos, quantos) sem aplicá-lo; valide o plano no servidor quando o sistema permitir, exija que o plano seja produzido e revisado antes da chamada real e compare depois o resultado real com ele.
-
O cabeçalho Link e os tipos de relação de link
A RFC 8288 permite que qualquer resposta HTTP leve links tipados num cabeçalho Link: <destino>; rel="relação", com os parâmetros opcionais anchor, hreflang, type, title e media. Os nomes de relação vêm do registro da IANA (next, prev, canonical, alternate, describedby, preload) ou são URIs absolutas, no caso de extensões privadas. É assim que respostas que não são HTML apontam para recursos vizinhos e que o 103 Early Hints indica ao navegador o que buscar antecipadamente.
-
HEAD e OPTIONS: o que respondem e para que os clientes os usam
HEAD é um GET sem corpo: mesmo status e mesmos cabeçalhos (Content-Length e Vary podem ser omitidos), é cacheável e serve para verificar links, consultar tamanhos e checar atualidade. OPTIONS pergunta quais opções de comunicação um recurso ou o servidor inteiro (OPTIONS *) suporta, costuma ser respondido com Allow, não é cacheável e transporta os preflights de CORS com Access-Control-Request-Method.
-
Verificação de assinaturas de requisições do Slack: X-Slack-Signature, janela de replay de 5 minutos e regra dos 3 segundos
O Slack assina as requisições como v0=<HMAC-SHA256 em hexadecimal> da string "v0:{timestamp}:{raw body}" no cabeçalho X-Slack-Signature, junto com X-Slack-Request-Timestamp; o exemplo do próprio Slack rejeita a requisição quando esse timestamp difere do horário local em mais de cinco minutos. Slash commands e payloads interativos também precisam ser confirmados em até três segundos, antes de qualquer processamento lento.
-
Como projetar um SDK sobre uma API HTTP
Um SDK deve tornar a chamada correta a mais fácil: modelos tipados, um único objeto cliente com a configuração, erros uniformes, retentativas com chaves de idempotência, iteradores de paginação e auxiliares para operações de longa duração, gerados a partir da descrição da API sempre que possível e escritos à mão apenas onde a geração não consegue expressar a intenção.
-
Como projetar webhooks de saída em que os receptores possam confiar
Assine cada entrega com um HMAC sobre o corpo e um timestamp, entregue ao menos uma vez com retentativas e ids de evento idempotentes, mantenha os payloads pequenos com um link para buscar os detalhes e permita que os receptores verifiquem a autenticidade sem segredos nas URLs.
-
Endpoints em lote e relatório de falhas parciais
Um endpoint em lote ou tem sucesso ou falha por inteiro, ou reporta o resultado de cada item; um único 200 não consegue expressar sucesso parcial. Por isso, escolha um comportamento por endpoint, identifique as falhas pela posição, limite o tamanho do lote e aplique autorização e limites de taxa por item.
-
Escolher códigos de status HTTP de forma deliberada
O código de status é a primeira coisa em que o cliente se baseia para decidir o que fazer: 200/201/204 para sucesso, 304 para sem alteração, 400/422 para entrada inválida, 401/403 para credenciais versus permissão, 404 para recurso inexistente, 409/412/428 para conflitos e pré-condições, 429/503 para tentar mais tarde.
-
Protocolos agente a agente em resumo: Agent Cards do A2A, tarefas e o lugar do MCP
O que o protocolo A2A (versão 1.0.0, Linux Foundation) padroniza entre agentes independentes: um Agent Card publicado em /.well-known/agent-card.json com capacidades, skills, endpoint e esquemas de segurança; tarefas com um ciclo de vida de submitted, working, input-required, auth-required, completed, failed, canceled e rejected; mensagens e artefatos compostos por parts; bindings JSON-RPC, gRPC e REST; e a descrição da própria especificação sobre como ele complementa o MCP.
-
Negociação com Accept-Language e seus limites
O Accept-Language envia uma lista ponderada de intervalos de idioma (da, en-gb;q=0.8, en;q=0.7); o servidor a compara com os idiomas disponíveis por filtragem ou lookup da RFC 4647, responde com Content-Language e Vary: Accept-Language e precisa de um fallback sensato quando o cabeçalho falta (o Googlebot não envia) ou está errado (o idioma do dispositivo não é a escolha do leitor). Use-o como primeira estimativa, não como único seletor.
Legível por máquina: JSON