Versionar API sem quebrar quem já integrou

No dia em que a primeira integração externa entra em produção, a sua API deixa de ser sua. Qualquer campo que você renomear vai quebrar código que você não controla, num horário que você não escolhe.

Versionar é o mecanismo para continuar evoluindo sem esse custo.

O que quebra e o que não quebra

A linha divisória é simples: quebra o que faz o cliente antigo parar de funcionar.

Não quebra:

• adicionar campo novo na resposta;
• adicionar parâmetro opcional na requisição;
• adicionar rota nova;
• adicionar valor novo num campo que já era aberto.

Quebra:

• remover ou renomear campo;
• mudar o tipo de um campo — número que vira texto derruba quem faz conta com ele;
• tornar obrigatório um parâmetro que era opcional;
• mudar o significado de um valor sem mudar o nome;
• mudar o código de status de uma situação existente.

Duas armadilhas escondidas nessa lista.

Adicionar valor novo a um campo fechado quebra, ainda que pareça adição. Se o status só podia ser ativo ou expirado e você acrescenta pendente, todo cliente que fez um switch sobre esses dois cai no caso não previsto.

Adicionar campo pode quebrar cliente que valida a resposta em modo estrito. É raro, mas acontece — e é motivo para documentar explicitamente que campo novo pode aparecer.

Onde colocar a versão

No caminho — /api/v1/orders — é o mais comum e o mais fácil de depurar: dá para ver a versão numa linha de log, num relatório de acesso, num curl colado no chamado. É a escolha que erra menos.

No cabeçalho é mais elegante do ponto de vista teórico e pior na prática, porque some de tudo que só mostra a URL.

No parâmetro funciona e polui a assinatura de cada chamada.

Se você ainda não tem versão nenhuma e já tem cliente, coloque no caminho e trate o que existe hoje como v1.

Não crie versão nova à toa

Versão nova é cara: você mantém duas, documenta duas, corrige bug em duas.

A maior parte da evolução cabe sem versão nova, se você projetar para adição. Campo novo, rota nova, parâmetro opcional — tudo isso convive.

Guarde a versão nova para o que realmente muda o contrato: outro modelo de dados, outra forma de autenticar, outra semântica.

Depreciar é um processo, não um aviso

Desligar versão antiga sem processo é derrubar cliente pago.

O que funciona:

1. Anuncie com data. "A v1 sai do ar em 12 meses, em tal dia." Sem data, ninguém migra.
2. Marque na resposta. Um cabeçalho de depreciação, com a data e um link para o guia de migração, chega a quem não lê e-mail.
3. Meça quem ainda usa. Você precisa saber quantas contas e quais.
4. Avise quem usa, individualmente. Comunicado no blog não alcança o desenvolvedor que integrou e saiu da empresa.
5. Faça um ensaio. Desligue por uma hora, num horário anunciado, meses antes. Quem estava dormindo acorda — e ainda dá tempo.
6. Só então desligue.

E escreva um guia de migração que diga o que mudou campo a campo, não só que existe uma versão nova.

O que ajuda quem integra

Especificação legível por máquina. Com OpenAPI, o cliente gera código e vê o diff entre versões. Sem ela, ele lê texto e adivinha.

Erros com código estável. Um campo de código próprio — SALDO_INSUFICIENTE, PEDIDO_JA_FINALIZADO — permite tratar programaticamente. Mensagem em texto muda com a tradução e não serve para decidir.

Documentar o que pode mudar sem aviso. Deixar claro que campos novos podem aparecer e que valores novos podem surgir em campos abertos poupa muita discussão depois.

O compromisso mínimo

Se você mantém uma API pública, três promessas resolvem quase tudo:

• não removemos nem renomeamos campo dentro de uma versão;
• podemos adicionar campo, e o cliente deve ignorar o que não conhece;
• versão em depreciação tem prazo anunciado com antecedência.

Escreva isso na documentação. É o que permite alguém integrar sem medo.

Se você está do lado de quem consome, o mesmo raciocínio aparece invertido em dez erros comuns ao integrar uma API — vários deles são suposições sobre o contrato que ninguém prometeu.

A API de números virtuais segue esse contrato: tudo sob /api/v1, com erro identificado por um code estável.