Versionamento de API é o processo de gerenciar alterações na interface sem quebrar quem já consome. Na prática, evite quebras versionando desde o início, mantendo compatibilidade, documentando mudanças e avisando sobre deprecação com antecedência. Assim, consumidores migram no próprio ritmo.
1. Versione desde o primeiro endpoint
Adicionar versão depois que a API já tem consumidores é retrabalho garantido. Defina o esquema (path, header ou query) antes do primeiro deploy. Critério: se um cliente já está em produção, mudar o esquema de versionamento exige nova rota e aviso prévio.
2. Prefira versionamento no path
Use /v1/recurso. É explícito, cacheável e fácil de testar no navegador. Em APIs públicas, a maioria dos guias adota esse padrão. Ressalva: se sua API é interna e o gateway já roteia por header, mantenha o header para não duplicar lógica.
3. Trate mudanças incompatíveis como nova versão
Remover campo, alterar tipo ou mudar significado de parâmetro quebra contrato. Nesses casos, suba /v2. Exemplo: trocar "idade": 30 por "idade": "30" quebra parsers tipados.
4. Mantenha compatibilidade para trás
Adicione campos opcionais em vez de remover. Consumidores antigos ignoram o que não conhecem. Critério: um cliente que não atualizou em 6 meses ainda deve funcionar.
5. Documente cada mudança no changelog
Registre data, versão e impacto. Sem changelog, o consumidor descobre a quebra em produção.
6. Anuncie deprecação com prazo
Defina janela mínima (por exemplo, 90 dias) e comunique por e-mail e docs. Sem prazo, ninguém migra.
7. Use feature flags para transições
Ligue a nova versão para um grupo pequeno antes de expor a todos. Isso reduz o raio de impacto.
8. Automatize testes de contrato
Rode testes que comparam o schema atual com o anterior. Se um campo obrigatório sumir, o build falha.
9. Monitore uso por versão
Saiba quantos clientes ainda chamam /v1. Sem métrica, você desliga a versão no escuro.
10. Padronize erros entre versões
Mantenha formato de erro estável. Mudar o corpo do erro também é quebra.
11. Evite versionar por data
Datas confundem e não indicam compatibilidade. Prefira números sequenciais.
12. Documente o ciclo de vida
Deixe claro quanto tempo cada versão vive. Isso orienta o planejamento do consumidor.
13. Faça revisão de contrato antes do release
Um par de olhos extra pega quebra acidental. Custa pouco e evita incidente.
Para APIs internas com poucos consumidores, comece pelas práticas 1, 3 e 4. Para APIs públicas, some 5, 6 e 9. O ganho aparece na primeira mudança que não vira incidente.
FAQ
O que é versionamento de API?
É o processo de gerenciar alterações na interface da API sem quebrar consumidores existentes. Envolve definir esquema de versão, manter compatibilidade e comunicar mudanças.
Qual a melhor forma de versionar?
Não há única resposta. Path (/v1/) é o mais comum em APIs públicas por ser explícito. Header funciona bem em APIs internas com gateway. Escolha uma e documente.
Quando criar uma nova versão?
Quando a mudança é incompatível: remoção de campo, alteração de tipo ou mudança de significado. Mudanças compatíveis podem entrar na versão atual.
Como avisar sobre deprecação?
Com antecedência mínima definida, por e-mail, changelog e documentação. Inclua data de desligamento e alternativa.
Versionar por data é ruim?
Pode confundir, pois a data não indica compatibilidade. Números sequenciais são mais claros para o consumidor.
Preciso versionar API interna?
Sim, se há mais de um consumidor. Mesmo interno, mudança inesperada quebra integração e gera retrabalho.