Changelog de API: o que publicar e quem lê

Um changelog de API é o registro datado de cada mudança que um chamador poderia notar, escrito para quem integra com a API, não para o time que a lança. Esse público é o que o torna um documento diferente de um changelog de produto: o leitor está decidindo se o próprio código vai continuar funcionando no mês seguinte. A maioria falha do mesmo jeito, sendo uma cópia filtrada de um feed interno de releases, de modo que um campo removido acaba ao lado de uma correção de texto com o mesmo peso, e nenhum dos dois é lido.

O que é um changelog de API?

É o registro público e datado de mudanças em uma interface contra a qual outras pessoas escreveram código. O teste útil para saber se algo pertence ali não tem nada a ver com o tamanho da mudança internamente. Ele pergunta se um chamador correto, escrito no ano passado e nunca mais tocado, poderia se comportar de forma diferente por causa dela. Esse teste admite algumas mudanças bem pequenas e exclui algumas bem grandes.

Tudo abaixo assume que quem chama está fora da empresa e é efetivamente inalcançável a não ser por este documento. Quando quem chama é outro time da mesma empresa, a conta muda o suficiente para merecer um tratamento próprio; changelogs de API interna cobre o que esse público precisa em vez disso.

Como escrever um guia de migração de API cobre esse último documento por completo; resumindo, é para onde uma entrada de mudança incompatível deveria linkar, em vez de tentar substituí-lo.

Os cinco são documentos separados com ciclos de vida separados. Um aviso de depreciação é uma promessa com data, e também pertence ao changelog, mas uma entrada de changelog é escrita uma vez, enquanto uma depreciação é acompanhada até seu sunset. Confundir os dois é o motivo pelo qual sunsets são perdidos.

O que deve entrar em uma única entrada?

Seis coisas, e as três primeiras são as que costumam faltar. A mudança em si, formulada em termos da requisição ou resposta, não do componente interno. Se ela quebra um chamador correto. O que o chamador precisa fazer, incluindo “nada”. A data em que passou a valer. A versão ou versões afetadas. Um link para o guia de migração, quando existir.

Uma entrada que diz “endpoint de accounts melhorado” falha em todas as seis. Uma entrada que diz “o campo accounts.type agora retorna individual onde antes retornava personal; valores existentes permanecem inalterados para contas criadas antes de 2 de setembro; nenhuma ação é necessária a menos que você compare a string” responde às seis em uma frase.

Categorize as entradas por consequência, não por departamento. Três rótulos carregam quase todo o valor: breaking, additive e fixed. O Semantic Versioning já define os dois primeiros com precisão, e emprestar suas definições em vez de inventar as próprias significa que um leitor que conhece semver conhece seus rótulos. O Keep a Changelog oferece um conjunto mais longo se você quiser, e sua regra central se aplica aqui com mais força do que em qualquer outro lugar: o log é para humanos, e um despejo de títulos de commit não é.

Em que um changelog de API difere das notas de versão?

Notas de versão descrevem o que o produto consegue fazer agora. Um changelog de API descreve qual é o contrato agora. O mesmo trabalho lançado geralmente produz uma entrada nos dois, formulada de forma diferente, porque os públicos precisam de coisas diferentes: um novo formato de exportação é uma funcionalidade para um usuário e um novo valor de enum para um chamador que decide com base nesse campo.

A consequência prática é que os dois não podem ser o mesmo feed com estilo diferente. Um chamador inscrito em tudo que você lança acaba se desinscrevendo, e então perde a mudança que quebra algo. Se você publica um feed, filtre-o; se publica dois, deixe o de API mais estreito e nunca deixe uma entrada de marketing entrar nele. Comparamos as duas formas lado a lado em changelog vs notas de versão.

Onde um changelog de API deve viver?

Ao lado da documentação de referência, em uma URL estável, com cada entrada endereçável individualmente por um fragmento ou caminho próprio. Chamadores linkam entradas em análises de incidentes e tickets internos, e uma entrada que não pode ser linkada acaba colada como print de tela em vez disso.

Publique-o também como saída legível por máquina, além da página. Um feed JSON seguindo a especificação JSON Feed ou um feed RSS não custa nada assim que as entradas viram dados estruturados, e é isso que permite que um cliente incorpore suas mudanças ao próprio processo de release. Essa é também a parte que decide se alguém constrói em cima disso. O GitHub documenta suas versões da REST API bem ao lado da referência pelo mesmo motivo: a política de versionamento faz parte da interface.

Como é uma boa entrada na prática?

Três entradas da mesma semana, na forma descrita acima:

2026-09-02  Breaking  v2
  `POST /invoices` agora rejeita uma `currency` que não corresponde
  à moeda da conta do cliente, retornando 422 em vez de converter
  silenciosamente. Chamadores que dependiam da conversão precisam
  enviar a moeda da conta. Afeta apenas v2; v1 permanece inalterado
  até o sunset em 2027-01-15.

2026-09-02  Additive  v1, v2
  `Invoice` ganha um timestamp `settled_at`, nulo até a fatura ser
  quitada. Nenhuma ação necessária. Clientes que rejeitam campos
  desconhecidos devem ser atualizados.

2026-08-31  Fixed  v2
  `GET /invoices?status=` retornava uma página vazia em vez de um
  400 para um status desconhecido. Agora retorna 400 com os valores
  aceitos. Chamadores com um erro de digitação antes viam zero
  resultados, agora veem um erro.

A terceira é o tipo mais frequentemente omitido, porque internamente é uma correção de bug. Para um chamador que construiu um retry em torno daquela página vazia, é uma mudança de comportamento, e a entrada é o que evita o ticket de suporte. O rótulo diz fixed e o corpo diz o que um chamador poderia notar, o que é a distinção que mantém o log honesto sem inflar cada correção para mudança que quebra algo.

Como os chamadores se inscrevem nisso?

Dê a eles mais de um canal, porque têm tarefas diferentes. Um feed para o desenvolvedor que quer tudo. E-mail para quem só quer mudanças que quebram algo. Cabeçalhos de resposta para o próprio código, o único assinante que nunca esquece de checar: o cabeçalho Sunset definido na RFC 8594 coloca a data de retirada na resposta, onde uma biblioteca cliente pode registrá-la.

O canal que a maioria dos times pula é o direto. Se um chamador usou na semana passada o campo que você está mudando, você sabe quem é essa pessoa, e um e-mail para essas contas vale mais do que qualquer transmissão geral. É a mesma disciplina de fechar o loop de feedback do cliente, aplicada a uma mudança que ninguém pediu: as pessoas afetadas são avisadas individualmente, e todas as outras recebem o feed. Um webhook é um quarto canal com o próprio jeito de falhar que vale a pena conhecer antes de confiar nele: changelogs de webhook cobre por que uma mudança de payload ali quebra em silêncio, sem quem chame para rejeitar a nova forma.

Como escrever uma entrada para uma mudança que quebra algo?

Comece pela quebra, não pelo motivo. Um chamador escaneando dez entradas precisa saber na primeira frase se essa vai custar trabalho a ele. Depois a data, as versões afetadas, a migração, e o prazo final se o comportamento antigo está sumindo em vez de mudando.

Coloque o mesmo conteúdo no aviso de depreciação, no cabeçalho de resposta e no e-mail direto, formulado de forma consistente, e dê aos quatro a mesma data. A divergência entre eles é a falha que transforma uma mudança planejada em um incidente, porque o chamador que leu só um deles age na data errada. O que é uma mudança que quebra algo cobre a decisão em si, e como depreciar uma API cobre o cronograma que vem depois.

No changeloop, uma mudança de API se torna uma entrada quando o pull request é mesclado, alguém edita e aprova o rascunho, e a entrada é publicada no feed e no widget no mesmo momento em que um chamador cujo feedback pelo widget virou a issue do GitHub que o pull request fecha é avisado nessa issue. O passo de revisão é o que importa aqui: um changelog de API é um documento contratual, e nenhum rascunho deveria chegar a um chamador sem que uma pessoa o tivesse lido.

FAQ

Toda mudança de API precisa de uma entrada de changelog? Toda mudança que um chamador correto poderia notar, sim, incluindo as que você considera internas. Mudanças sem efeito observável na requisição ou resposta não, e adicioná-las treina os leitores a passar os olhos rapidamente.

O changelog de API deveria viver na documentação ou no site de marketing? Na documentação, bem ao lado da referência. O leitor geralmente já está lá, e um changelog no site de marketing tende a ganhar um público para o qual não foi escrito.

Até quando ele deveria voltar no tempo? Indefinidamente. Entradas são citadas anos depois em análises de incidentes, e um log truncado quebra esses links. Pagine em vez de podar.

Preciso de um changelog separado por versão de API? Não, um único log com um campo de versão por entrada é mais fácil de ler e buscar. Filtrar por versão é uma funcionalidade da página, não um motivo para dividir o documento.

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