O Que é API Versioning? Evoluir uma Interface Sem Quebrá-la
API versioning permite introduzir breaking changes rodando uma nova versão de uma interface ao lado da antiga até os clientes migrarem.
Às vezes um breaking change é inevitável. API versioning é como você o shipa sem forçar todo cliente a atualizar de uma vez: expor uma nova versão, manter a antiga rodando e deixar os consumers migrarem no próprio ritmo. O custo é manter e testar múltiplas versões até a antiga poder ser aposentada.
Por que versionar
Uma API versionada pode evoluir, mesmo com breaking changes, sem coordenar todo cliente. Clientes antigos permanecem na versão antiga; clientes novos adotam a nova. Esse desacoplamento é essencial para APIs públicas e grandes conjuntos de microservices.
Estratégias comuns
- Versionamento no path da URL (/v1/, /v2/) - explícito e fácil de rotear.
- Versionamento por header ou media-type - mantém as URLs estáveis.
- Versionamento por query-parameter - simples mas fácil de ignorar.
- Sem versionamento, apenas mudanças aditivas - viável se você nunca quebra.
O custo de múltiplas versões
Cada versão viva é código que você precisa manter, testar e proteger. Versões se acumulam, então uma política de deprecação, anunciar, sunset, remover, é o que evita que a superfície cresça sem limite.
Testando cada versão suportada
O CI precisa testar cada versão viva, muitas vezes como um matrix, para garantir que nenhuma regride enquanto a nova evolui. A pipeline cresce com o número de versões suportadas, o que por si só é um argumento para aposentar as antigas prontamente.
Fazendo deploy de uma nova versão
Uma nova versão geralmente é shipada de forma aditiva, a antiga continua atendendo, então o próprio deploy é não-breaking. O breaking change fica contido dentro da nova versão, o que torna o rollout seguro e o rollback simples.
Matrizes de versão em runners rápidos
Testar várias versões de API em paralelo é um matrix build natural. Runners gerenciados que escalam horizontalmente (como o Latchkey) rodam esses jobs de versão concorrentemente para que a suíte termine rápido apesar da cobertura extra.
Principais conclusões
- API versioning roda versões novas e antigas da interface lado a lado.
- Permite shipar breaking changes sem forçar uma atualização sincronizada dos clientes.
- Cada versão viva é custo de manutenção e teste, então deprecie as antigas deliberadamente.