Versionamento de contrato de API: como mudar sem quebrar quem já está integrado

O que é o "contrato" de uma API

Contrato de API é o conjunto de regras combinadas entre quem oferece a API e quem consome ela — quais campos existem, que formato cada um tem, o que é obrigatório e o que é opcional. Enquanto esse contrato não muda, qualquer sistema integrado continua funcionando exatamente como antes.

Por que mudar um contrato sem versionar é arriscado

Alterar o contrato existente — mudar um campo, remover algo que já era usado — sem oferecer uma versão nova em paralelo, força todo sistema já integrado a se adaptar imediatamente, no exato momento em que a mudança é publicada, sem nenhuma margem de tempo pra se preparar.

Como versionamento resolve isso

Em vez de alterar o contrato existente, uma nova versão é publicada ao lado da anterior — geralmente identificada por um número ou data — mantendo a versão antiga funcionando por um período de transição, enquanto quem integra migra no próprio ritmo pra versão nova.

O que um bom período de transição inclui

• Prazo claro de até quando a versão antiga continuará disponível;
• Documentação da diferença entre as versões, facilitando a migração de quem já está integrado;
• Aviso com antecedência real, não apenas no dia em que a versão antiga é efetivamente desativada.

Do lado de quem consome a API, não de quem publica

Quando é a consolidadora que versiona bem seu contrato, quem integra ganha previsibilidade — mas isso não elimina a necessidade de acompanhar ativamente os avisos de versão, porque mesmo um período de transição generoso perde o valor se ninguém percebe que ele está correndo.

Versionar também é uma disciplina interna

O mesmo princípio vale ao expor uma API própria pra outros sistemas consumirem — versionar o contrato desde o início, mesmo antes de ter qualquer necessidade imediata de mudança, evita a pressão de ter que quebrar compatibilidade de forma abrupta lá na frente, quando já existir dependência real de terceiros.