Como escrever um guia de migração de API

Um guia de migração de API é o documento que transforma uma mudança incompatível em uma checklist em vez de uma interrupção: o que mudou, o que fazer a respeito, e até quando. Uma entrada de changelog pode nomear uma mudança incompatível em duas frases; um guia de migração é o que quem chama realmente abre quando essas duas frases dizem “isso quebra você” e ela precisa saber exatamente o que editar. Publicar a entrada sem o guia é como quem chama descobre uma mudança incompatível por um ticket de suporte em vez do documento escrito para evitar exatamente isso.

O que é um guia de migração de API?

Um documento passo a passo que leva quem chama da forma antiga de uma API para a nova, escrito para alguém com código para mudar, não para alguém que ainda está decidindo se adota a API. Essa distinção importa: um guia de migração assume uma integração existente e tráfego de produção existente, então precisa cobrir rollback, migração parcial, e como saber se a migração funcionou, nada disso necessário para um guia de primeira integração.

Um guia de migração geralmente fica entre os dois últimos: um aviso de depreciação dispara um relógio, e o guia de migração é o que quem chama segue antes que esse relógio se esgote.

Quando uma mudança precisa de um guia de migração, não só de uma entrada de changelog?

Quando há mais de um passo entre o comportamento antigo e o novo, ou quando a mudança toca pontos de chamada suficientes para que quem chama se beneficie mais de um exemplo trabalhado do que de uma descrição. O que é uma mudança incompatível, e como lançá-la cobre o teste para saber se uma mudança é incompatível; se a resposta é sim, a segunda pergunta é se o conserto é uma edição de uma linha ou uma migração de verdade. Um campo renomeado, quem chama consegue lidar só com a entrada de changelog. Uma mudança em autenticação, paginação ou tratamento de erros quase sempre merece um guia, porque o código de substituição correto não é óbvio a partir de uma descrição de uma frase.

O que um guia de migração precisa conter?

Cinco coisas, e pular qualquer uma delas é como um guia vira uma página que quem chama lê uma vez e depois volta a tentativa e erro. O código antigo, mostrado como realmente apareceria em um projeto. O código novo, mostrado da mesma forma, não como uma descrição abstrata da diferença. O que quebra se nada mudar, dito claramente, porque “nada” é uma resposta válida e comum que quem chama ainda precisa ouvir explicitamente. Uma forma de verificar se a migração funcionou, como um campo de resposta ou um código de status para checar. E um cronograma: quando o comportamento antigo para de funcionar, e se ambas as formas ficam disponíveis nesse meio-tempo.

## Migrando campos de moeda de float para integer (v3.0.0)

Antes:
  { "amount": 19.99 }

Depois:
  { "amount": 1999 }  // menor unidade monetária (centavos)

O que muda: `amount` agora é um inteiro na menor unidade da moeda da
conta. Código que lê `amount` como float vai ler um valor 100x maior
demais a partir de 1º de outubro de 2026.

Verificar: depois da migração, uma cobrança de $19,99 deve ser lida
como `amount: 1999`, não como `amount: 19.99`.

Cronograma: v2 continua retornando floats até 15 de janeiro de 2027.
v3 retorna inteiros desde o lançamento. As duas versões estão ativas
agora.

Cada uma dessas cinco coisas responde a uma pergunta que quem chama teria que adivinhar ou perguntar ao suporte, e esse é exatamente o custo real que um guia de migração economiza.

Quem deveria escrevê-lo, e quando?

Quem projetou a mudança, no mesmo momento em que ela é lançada, não um time de suporte reconstruindo-o depois a partir de tickets. Quem tomou a decisão sabe em quais partes do comportamento antigo ninguém deveria ter confiado e quais eram um contrato acidental; um guia escrito depois por alguém sem esse contexto tende a explicar demais o óbvio ou a perder aquele um caso extremo que realmente quebra as pessoas. O guia e a entrada de changelog que anuncia a mudança incompatível deveriam sair juntos, com a entrada linkando para o guia em vez de repeti-lo.

Como isso se relaciona com versionamento e o changelog de API?

Diretamente: um guia de migração é a versão detalhada do que uma entrada MAJOR em semantic versioning e o seu changelog só resume em uma frase. A entrada de changelog diz que uma mudança é incompatível e a grandes traços o que mudou; o guia de migração é o link que essa entrada deveria carregar. Changelog de API: o que publicar e quem lê lista o guia de migração como um dos cinco documentos que uma API mantém, cada um respondendo a uma pergunta diferente; esse é o que responde “como eu realmente saio de A para B”, e merece sua própria página justamente porque essa resposta costuma ser longa demais para uma entrada de changelog.

Por quanto tempo um guia de migração deveria ficar publicado?

Pelo menos enquanto o comportamento antigo continuar acessível, e idealmente depois também. Quem migra dezoito meses atrasada, depois de ignorar três avisos de depreciação, ainda precisa do guia, e apagá-lo no dia em que o comportamento antigo é desligado só garante que quem mais precisa dele não vai encontrá-lo. Mantenha-o em uma URL estável e atualize a seção de cronograma em vez de retirar a página. O próprio guia de upgrade da Stripe é um exemplo público do padrão: uma única página, mantida atualizada release após release, em vez de um documento novo por versão que fica desatualizado assim que a próxima sai. O guia de vocês merece um lugar igualmente fácil de achar, ao lado da documentação que quem chama já está lendo, em vez de enterrado em um arquivo de blog.

FAQ

Toda mudança incompatível precisa de um guia de migração? Não. Uma mudança que quem chama consegue resolver só com a entrada de changelog, como um único campo renomeado com uma substituição óbvia, não precisa de um guia separado. Uma mudança que toca vários pontos de chamada ou precisa de um exemplo trabalhado, precisa.

Um guia de migração deveria ficar com a documentação da API ou no changelog? Com a documentação, linkado da entrada de changelog. A entrada é o que uma assinante vê primeiro; o guia é o que ela precisa assim que decide agir, e pertence ao lado do material de referência que quem chama já está usando.

Qual é a diferença entre um guia de migração e um aviso de depreciação? Um aviso de depreciação declara que algo vai desaparecer e até quando. Um guia de migração são as instruções sobre o que fazer a respeito. Um aviso de depreciação sem guia de migração linkado dá a quem chama um prazo sem dizer como cumpri-lo.

O comportamento antigo e o novo deveriam ser documentados juntos durante uma janela de migração? Sim, na mesma página se possível, para que quem chama veja exatamente o que mudou em vez de montar isso a partir de dois documentos separados escritos em momentos diferentes.

As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.

Relacionado na changeloop: Documentação para desenvolvedores, Exemplos de changelog