Versionamento de API
Como evoluir um contrato sem quebrar quem já o usa, e quais mudanças quebram de verdade.
As decisões de versionamento são quatro: como evitar versões novas, onde a versão aparece quando for inevitável, como conduzir uma mudança incompatível e como detectar uma antes que chegue a produção.
Primeiro, evitar a versão nova
A maioria das mudanças pode ser feita de forma compatível, com um pouco de planejamento.
| Necessidade | Forma compatível |
|---|---|
| Renomear um campo | Acrescentar o nome novo, manter o antigo por um tempo, devolver os dois, depois remover o antigo |
| Mudar o tipo de um campo | Acrescentar um campo novo com o tipo novo (valorCentavos ao lado de valor) |
| Mudar o comportamento de uma rota | Uma rota nova, ou um parâmetro opcional que liga o comportamento novo |
| Tornar um campo obrigatório | Manter opcional, com um valor padrão no servidor |
| Remover um campo | Marcar como obsoleto, medir o uso, avisar quem usa, só então remover |
Essa técnica se chama expandir e contrair (expand and contract): primeiro a API acrescenta o formato novo, convivendo com o antigo; os clientes migram; depois a API remove o antigo. Nenhum momento exige que servidor e clientes mudem juntos.
Onde a versão aparece
Quando a versão nova é inevitável, ela precisa aparecer em algum lugar do pedido.
| Onde | Exemplo | Vantagens | Cuidados |
|---|---|---|---|
| No caminho | /v1/pedidos, /v2/pedidos | Visível, fácil de rotear, de testar no navegador e de cachear | Muda o endereço do recurso |
| Num cabeçalho | Api-Version: 2 | Endereços estáveis | Invisível em logs e no navegador; cache precisa considerar o cabeçalho |
| No tipo de conteúdo | Accept: application/vnd.loja.v2+json | Fiel ao HTTP | Complexo para os clientes; pouco usado |
| Por data | Api-Version: 2026-03-10 | Mudanças pequenas e frequentes; cada cliente fica na data em que integrou | Exige uma camada que traduza entre as versões |
O caminho é a escolha mais comum e a mais simples de operar. O versionamento por data é usado por APIs públicas com muitos integradores, como a da Stripe: cada cliente fica preso à versão da data em que começou, e o servidor converte as respostas para aquele formato.
Seja qual for a escolha, versione a API inteira, e não rota por rota. Uma /v2/pedidos ao lado de /v1/clientes obriga cada cliente a saber a versão de cada rota.
Conduzir uma mudança incompatível
| Etapa | O que fazer |
|---|---|
| 1. Publicar a versão nova | A antiga continua funcionando, sem mudanças |
| 2. Marcar a antiga como obsoleta | Na documentação e nas respostas, com os cabeçalhos Deprecation e Sunset, que dizem a data de desligamento |
| 3. Medir quem ainda usa | Registrar a versão em cada pedido, por cliente ou chave de API |
| 4. Avisar diretamente | Os clientes que ainda usam a versão antiga, com o guia de migração |
| 5. Desligar na data anunciada | Antes, um ou dois "apagões" curtos e programados ajudam a revelar quem não migrou |
HTTP/1.1 200 OK
Deprecation: @1767225600
Sunset: Thu, 01 Oct 2026 00:00:00 GMT
Link: <https://docs.loja.com.br/migracao-v2>; rel="deprecation"O cabeçalho Sunset (RFC 8594) informa quando a rota deixará de funcionar; o Deprecation (RFC 9745) informa que ela está obsoleta e desde quando. Clientes e ferramentas podem detectá-los e avisar os desenvolvedores.
Detectar mudanças incompatíveis antes do deploy
| Técnica | Como funciona |
|---|---|
| Comparar o OpenAPI | Ferramentas como oasdiff comparam o contrato publicado com o novo e apontam mudanças incompatíveis no CI |
| Testes de contrato | Os clientes registram o que esperam da API, e o servidor é testado contra essas expectativas (o tópico de testes de contrato aprofunda) |
| Revisão do contrato | Mudanças no OpenAPI exigem aprovação de quem cuida da API |
| Tráfego real | Reproduzir pedidos reais contra a versão nova antes de liberar |
A comparação de contratos no CI é o investimento com melhor retorno: ela pega, por exemplo, um campo removido ou uma enumeração alterada no momento em que alguém abre o pull request.
O lado do cliente
| Prática | Por quê |
|---|---|
| Ignorar campos desconhecidos | Campos novos não quebram a leitura |
| Tratar valores desconhecidos de enumerações | Status e tipos novos não quebram a leitura; o cliente decide o que exibir |
| Não usar modos estritos para ler respostas | Eles transformam toda evolução do servidor em falha |
| Fixar a versão da API nas chamadas | Uma mudança de versão vira uma decisão do cliente, e não uma surpresa |
Monitorar os cabeçalhos Deprecation e Sunset | Aviso antecipado de desligamento |
Resumo da decisão
- Evite versões novas com expandir e contrair.
- Clientes tolerantes: ignore o desconhecido, trate enumerações como abertas.
- Documente quais enumerações podem ganhar valores.
- Versão no caminho, para a API inteira, quando inevitável.
- Desligue com processo: obsolescência marcada, uso medido, aviso direto, data cumprida.
- Compare o contrato no CI para pegar mudanças incompatíveis antes do deploy.
O próximo nível mostra clientes tolerantes nas cinco linguagens, executados contra as respostas do teste, e como acompanhar o uso das versões no servidor.
Prompts para aprofundar
Ao abrir no ChatGPT ou no Claude, o prompt é enviado ao serviço escolhido pela URL e também fica copiado na sua área de transferência.
Escolher a estratégia de versionamento
Quero escolher como versionar a API do meu sistema. Pergunte quem consome a API (aplicativos próprios, parceiros, público), com que frequência ela muda e se já existe alguma versão publicada. Compare para o meu caso: versão no caminho, em cabeçalho, no tipo de conteúdo e por data. Fale de facilidade para os clientes, cache, roteamento, logs e custo de manter. Termine com a recomendação, a convenção exata a usar e as regras para decidir quando uma mudança justifica uma versão nova.
Planejar o desligamento de uma versão antiga
Preciso desligar uma versão antiga da minha API sem prejudicar quem ainda a usa. Pergunte quantos clientes existem, se eu sei quem são e como eles se autenticam. Monte comigo o plano: 1. Como medir quem ainda usa a versão antiga. 2. Como marcar a versão como obsoleta na documentação e nas respostas, com os cabeçalhos Deprecation e Sunset. 3. O cronograma de avisos e o conteúdo do guia de migração. 4. Apagões programados antes do desligamento definitivo. 5. O que fazer com clientes que não migrarem a tempo.
Fazer uma mudança incompatível de forma compatível
Preciso fazer uma mudança na minha API que, à primeira vista, quebraria os clientes. Peça que eu descreva a mudança (por exemplo, renomear um campo, mudar o tipo de um valor monetário de número para centavos, separar um campo de endereço em vários). Mostre como fazer a mudança com a técnica de expandir e contrair: 1. A fase de expansão: o que acrescentar sem remover nada. 2. Como servidor e clientes convivem com os dois formatos. 3. Como medir quando todos migraram. 4. A fase de contração. Inclua exemplos das respostas da API em cada fase.