API versioning estratégias: guia prático para não quebrar integrações

API versioning é o conjunto de estratégias para evoluir uma API sem quebrar integrações existentes. Na prática, é a resposta a uma pergunta chata: como mudo o formato de um campo ou removo um endpoint sem que o sistema de outra pessoa pare de funcionar na madrugada de domingo?

Não existe estratégia universal. O que existe é um trade-off entre clareza para o consumidor, controle para quem mantém a API e custo operacional. Vou passar pelas abordagens que vejo com mais frequência, com o que cada uma resolve e onde ela costuma doer.

O que é API versioning, de forma direta

É o mecanismo que permite que duas versões do mesmo recurso coexistam. Quando você adiciona um campo obrigatório, renomeia algo ou muda o comportamento de um endpoint, clientes antigos podem quebrar. O versionamento cria uma camada explícita de contrato: quem está na v1 continua recebendo o comportamento antigo; quem migra para a v2 recebe o novo.

Sem versionamento, toda mudança vira uma aposta. E aposta, em produção, costuma sair cara.

Quais são as estratégias mais comuns de versionamento de API

Versionamento na URL

É o mais visível: /v1/pedidos, /v2/pedidos. Vantagens: fácil de ler, fácil de testar no navegador, fácil de documentar. Desvantagem: mistura versionamento com a estrutura do recurso, o que incomoda puristas de REST. Para APIs públicas, é o que eu vejo funcionar com menos atrito, porque o consumidor enxerga a versão sem precisar ler documentação.

Versionamento por cabeçalho

Aqui a versão vai em um header customizado, tipo X-API-Version: 2, ou no Accept. Mantém a URL limpa e permite evoluir sem mudar o caminho. O problema é o atrito: quem consome precisa lembrar de mandar o header. Em APIs internas com poucos clientes, funciona bem. Em APIs abertas, gera suporte.

Versionamento por media type

Usa Accept: application/vnd.suaapi.v2+json. É elegante em teoria e alinhado com content negotiation. Na prática, exige que o consumidor entenda esse detalhe e que o time mantenha uma matriz de tipos. Vejo pouco uso fora de contextos muito controlados.

Versionamento por data

Cada requisição informa uma data e a API responde com o comportamento vigente naquele momento, algo como o Stripe faz. Resolve bem mudanças graduais, mas exige disciplina interna para não acumular comportamentos antigos indefinidamente.

Versionamento por parâmetro de query

?version=2. Simples de implementar, mas some da URL canônica e polui a query string. Costuma aparecer como paliativo, não como estratégia principal.

Quando usar cada estratégia

Não existe resposta única. O critério que uso é: quem consome a API e quanto controle eu tenho sobre esse público?

• API pública, muitos clientes desconhecidos: URL costuma ser a escolha mais previsível.
• API interna, poucos times: cabeçalho ou media type funcionam sem grande custo.
• Mudanças graduais com clientes que acompanham releases: versionamento por data pode reduzir migrações traumáticas.
• Protótipo ou produto em validação: qualquer estratégia serve, desde que você documente.

O que não funciona é não decidir. Sem regra clara, cada time inventa a sua e o suporte vira caos.

Erros comuns que vejo em projetos reais

Manter versões antigas para sempre. Toda versão viva custa testes, correções e documentação. Defina uma política de depreciação, com prazo comunicado e, se possível, avisos no próprio retorno da API.

Versionar tudo o tempo todo. Adicionar um campo opcional normalmente não exige nova versão. Versionar por qualquer coisa multiplica a manutenção sem ganho real.

Quebrar contrato sem aviso. Remover campo, mudar tipo ou alterar semântica de erro sem transição é o jeito mais rápido de perder confiança de quem integra.

Não documentar o que mudou. Um changelog honesto vale mais que qualquer estratégia sofisticada.

Resumo prático

API versioning é sobre não quebrar quem já confia na sua API. Escolha uma estratégia, documente a política de depreciação e trate compatibilidade como parte do produto, não como detalhe técnico.

FAQ

O que é API versioning em uma frase?

É o conjunto de práticas que permite alterar uma API sem quebrar integrações existentes, mantendo versões antigas funcionando enquanto novos comportamentos são introduzidos. Sem isso, qualquer mudança vira risco para quem consome.

Qual a estratégia de versionamento mais usada?

Versionamento na URL é a mais comum em APIs públicas, pela clareza e facilidade de teste. Cabeçalho e media type aparecem mais em APIs internas ou com poucos consumidores controlados, onde o atrito de adoção é menor.

Versionamento de API é obrigatório?

Não é obrigatório por lei ou norma técnica, mas é uma prática recomendada quando a API tem consumidores externos. Sem versionamento, mudanças incompatíveis podem derrubar integrações de terceiros sem aviso prévio.

Como depreciar uma versão de API com segurança?

Comunique o prazo com antecedência, mantenha a versão antiga funcionando durante a transição, ofereça guia de migração e, se possível, inclua avisos no retorno da própria API. Depois do prazo, desligue com registro claro.

Versionamento semântico resolve versionamento de API?

Ajuda, mas não resolve sozinho. Versionamento semântico organiza números de versão, não define como duas versões coexistem em produção. São conceitos complementares, não substitutos.

Toda mudança exige nova versão da API?

Não. Adições compatíveis, como campos opcionais, geralmente não exigem nova versão. Mudanças que quebram contrato, como remoção de campo ou alteração de tipo, pedem versionamento ou transição cuidadosa.