API versioning: estratégias que não quebram seus clientes
Breaking change sem versionamento queima confiança. URI, header ou parâmetro? Contratos, deprecações e comunicação.
Guia por tema
Design de APIs robustas: princípios REST, trade-offs do GraphQL, versionamento, autenticação, webhooks e idempotência em integrações reais.
3 tópicos · 11 artigos
Recursos, verbos HTTP, códigos de status e versionamento.
Breaking change sem versionamento queima confiança. URI, header ou parâmetro? Contratos, deprecações e comunicação.
A maioria das APIs trata erros de forma inconsistente. Um padrão bem definido reduz bugs de integração e facilita debug.
Authorization code com PKCE substituiu o fluxo implícito. Fluxo completo, validação de ID token e o padrão BFF para SPA sem token no localStorage.
Access token de 15 minutos, refresh token em cookie HttpOnly, lista de revogação no Redis e validação de claim em cada request. O fluxo completo em Node, do login ao logout.
Trade-offs e quando usar cada um.
GraphQL elimina over-fetching e cria complexidade própria. Onde ganha de REST hoje e onde virou peso morto.
Tokens, webhooks e chamadas que podem ser repetidas com segurança.
OAuth 2.0 é protocolo; JWT é formato de token. O que as RFCs 7519, 8725 e 9700 dizem sobre validação, revogação e o que o OAuth exige hoje, como PKCE e redirect URI exato.
Rede interna não é confiável por padrão. mTLS, JWT entre serviços e workload identity em ambientes reais.
.env commitado é o vazamento mais comum do mundo dev. Cofres, rotação e injeção segura de credenciais.
Webhooks falham em silêncio: duplicados, fora de ordem, perdidos. Checklist completo para receber eventos sem perder nenhum.
Injection e broken access control lideram o OWASP Top 10. Teste com dois usuários, CSP, Argon2 e o checklist que fecha um risco real por vez no CI.
Token bucket, fixed window e sliding log resolvem problemas diferentes. Chave por IP, usuário ou API key, headers que o cliente lê e limite por rota. Código com Redis e express-rate-limit.
REST é mais simples e aproveita cache HTTP; GraphQL é flexível, mas mais complexo de operar. Para a maioria dos casos, comece com REST.
Para times pequenos, geralmente sim. Ele compensa quando há muitos clientes com necessidades de dados diferentes consumindo a mesma API.
Versão na URL (/v1/, /v2/) é a forma mais clara para quem consome. Versão por header é uma alternativa quando você quer URLs estáveis.
Na comunicação interna entre serviços, onde performance e contratos tipados importam. Para APIs públicas, prefira REST: gRPC exige HTTP/2 e payload binário.