APIs públicas e breaking changes

Nível: B2

Objetivo

Comunicar mudanças em APIs públicas em inglês técnico: distinguir breaking change de non-breaking change, descrever versionamento, deprecation e migration guide, articular uma política de backward compatibility e discutir contract testing entre o time produtor e os consumidores.

Explicação

Manter uma public API significa equilibrar dois contratos ao mesmo tempo: o contrato técnico (endpoints, payloads, status codes) e o contrato social com quem consome a API. Em B2, espera-se que você seja explícito sobre o que mudou, por que mudou, e o que o consumidor precisa fazer — em frases que misturam voz passiva, modal verbs e noun clauses.

1. Breaking change vs. non-breaking change

A pergunta central é: *se um consumidor atualizar a SDK ou re-deployar hoje, o código dele continua funcionando?* Se a resposta é não, é uma breaking change. Se a resposta é sim, é uma non-breaking change.

Em comunicação técnica, prefira a voz passiva para descrever o efeito:

• `The /v1/charges endpoint has been removed.`
• `The `currency` field has been renamed to `iso_currency`.`
• `The default page size has been increased from 20 to 50.`

A passiva foca no que mudou, não em quem mudou — útil em release notes e migration guides.

2. Semantic versioning (semver)

APIs públicas quase sempre seguem semver: `MAJOR.MINOR.PATCH`.

• MAJOR sobe quando há breaking change (`1.x.x` → `2.0.0`).
• MINOR sobe quando há funcionalidade nova compatível (`1.4.x` → `1.5.0`).
• PATCH sobe para bug fixes compatíveis (`1.4.2` → `1.4.3`).

Frases típicas em release notes:

• `This release contains no breaking changes.`
• `Version 2.0.0 is a major release; please review the migration guide.`
• `We have bumped the minor version to 1.5.0.`

3. Versionamento na URL vs. no header

Existem duas estratégias comuns de versionamento:

• URL versioning: `/v1/charges`, `/v2/charges`. Fácil de testar, fácil de cachear.
• Header versioning: `Accept: application/vnd.acme.v2+json`. Mais limpo, mas exige cuidado com CDNs e proxies.

Em comunicação, use versioning como substantivo uncountable: `We chose URL-based versioning for clarity.` Para descrever a estratégia, prefira `URL-based`, `header-based`, `query-based` como adjetivos compostos.

4. Backward compatibility e deprecation

Backward compatibility é a promessa de que o código antigo continua funcionando. Deprecation é o aviso de que algo será removido no futuro, dando tempo para migrar.

Padrão típico de deprecation em três tempos:

1. Announce: anunciar a deprecation na release note, no blog e no changelog. Enviar email ou postar no fórum dos consumidores.
2. Warn: emitir um `Deprecation` header em cada resposta, ou um `Sunset` header, e logar warnings no servidor.
3. Sunset: remover o endpoint ou o campo depois de um `sunset date` claro.

Frases comuns:

• `The /v1/charges endpoint is deprecated and will be removed on March 31, 2027.`
• `Please migrate to /v2/charges before the sunset date.`
• `We strongly recommend that you upgrade your SDK to version 2.x.`
• `A `Deprecation: true` header has been added to every response from /v1/charges.`
• `The `Sunset` header is sent on all responses from the deprecated endpoint.`

Note o uso de modal verbs de recomendação (`should`, `recommend`, `strongly recommend`, `must`, `need to`) e de voz passiva (`has been added`, `is sent`). Essa combinação é o tom padrão de uma API policy.

5. Migration guide

A migration guide é o documento que diz, passo a passo, o que o consumidor precisa mudar. Em B2, espera-se clareza sobre:

• O que mudou (breaking changes listadas).
• Por que mudou (razão, trade-off, link para a RFC).
• O que fazer (mapeamento de campos, exemplos de request/response, snippets de código).
• Quando (sunset date, janela de suporte).
• Como pedir ajuda (canal de suporte, office hours, Slack de desenvolvedores).

Estrutura recomendada em frases:

• `The `currency` field has been renamed to `iso_currency` to align with the ISO 4217 standard.`
• `If you are still sending `currency`, the API will continue to accept it until March 31, 2027.`
• `To upgrade, replace every occurrence of `currency` with `iso_currency` in your request body.`

6. Contract testing

Contract testing valida que o produtor e o consumidor concordam sobre o formato da resposta. Em vez de rodar testes de integração pesados, cada lado publica um contrato (geralmente em formato OpenAPI ou em uma DSL como Pact), e os testes verificam que os dois lados ainda o cumprem.

Termos importantes:

• Consumer-driven contract: o consumidor define o que espera, o produtor verifica se continua entregando.
• Provider verification: o produtor roda os testes contra os contratos de todos os seus consumidores registrados.
• Pact / OpenAPI / Schema: o arquivo de contrato em si.

Frases comuns em PRs e code review:

• `The contract test failed because the new field is required but the provider does not return it.`
• `We need to update the OpenAPI schema before merging this change.`
• `Please regenerate the consumer pact after bumping the major version.`

7. Comunicar mudança para consumidores

A comunicação tem quatro audiências: engenheiros (mudança técnica), product managers (impacto no roadmap), suporte (perguntas de clientes) e líderes (risco de churn). Para cada uma, o tom muda, mas a mensagem central é a mesma.

Padrão recomendado de comunicação:

• Subject line claro: `[Action required] /v1/charges will be removed on March 31, 2027`.
• O que está mudando (uma frase).
• Por que (uma frase).
• O que você precisa fazer (passos numerados).
• Quando (datas concretas).
• Onde pedir ajuda (canal e responsável).

Exemplo em tom direto:

> Subject: `[Action required] /v1/charges deprecation — sunset on March 31, 2027` > > Starting today, `/v1/charges` is deprecated. The endpoint will continue to work, but we will add a `Deprecation` header to every response. On March 31, 2027, the endpoint will be removed. > > To migrate, please: > 1. Update your SDK to version 2.x. > 2. Replace `currency` with `iso_currency` in request bodies. > 3. Re-run your integration tests against the v2 sandbox. > > If you have questions, reply to this email or join office hours on Wednesdays at 10:00 BRT.

Esse tom combina voice passiva (is deprecated, will be added, will be removed), modal verbs de recomendação (please update, please replace, please re-run) e imperativos polidos (To migrate, please…). É a fórmula padrão de release notes e migration guides em B2.

Exemplos

Erros comuns

• Confundir breaking com broken: uma breaking change *vai quebrar* código existente; uma broken API *já está quebrada*. Use breaking change para mudanças planejadas.
• Escrever `deprecate` sem contexto: prefira `The /v1 endpoint has been deprecated` (passiva) em vez de `We deprecated the /v1 endpoint` quando a audiência é o consumidor, porque a passiva foca no objeto, não no time.
• Usar `remove` em vez de `sunset` em release notes formais: `sunset` é o termo padrão do setor para indicar o fim do suporte; `remove` é o verbo técnico no commit.
• Anunciar breaking change sem data: `We have removed the field` é informativo, mas `We have removed the field as of March 31, 2027` é acionável. Sempre inclua o sunset date.
• Escrever migration guide como bullet list sem exemplos: inclua um snippet de request/response antes e depois, e o mapeamento de campos.
• Chamar contract testing de `integration test`: contract testing é mais leve, é executado em CI, e não precisa do sistema completo no ar. Manter os termos separados ajuda na conversa técnica.
• Dizer `version 1` em vez de `v1` ou `version 1.x`: em release notes de API, a forma abreviada `v1`/`v2` é padrão. Use `version 1` apenas em prosa explicativa.
• Misturar `backward compatibility` e `backwards compatibility`: ambas existem, mas `backward compatibility` é a forma preferida em textos técnicos americanos e na maioria das API guidelines.
• Usar `will` em release notes já publicadas: prefira `has been removed` (passiva presente perfeita) para fatos consumados, e `will be removed on DATE` (passiva futura) para fatos planejados.

Prática guiada

Reescreva cada nota informal em tom de release note B2.

1. Mensagem de Slack solta

`removi o campo currency, agora é iso_currency` → `The `currency` field has been renamed to `iso_currency` to align with ISO 4217. Please update your request bodies before March 31, 2027.` (voz passiva + reason + prazo)

1. Aviso genérico de remoção

`o endpoint v1 vai sair do ar em algum momento` → `The /v1/charges endpoint is deprecated and will be removed on March 31, 2027. A `Deprecation: true` header has been added to every response.` (is deprecated + will be removed on DATE + has been added)

1. Pedido de mudança em PR

`atualiza o contrato do consumidor` → `Please regenerate the consumer pact after bumping the major version; the contract test is currently failing because the provider does not return the new required field.` (imperativo polido + because-clause)

1. Confirmação para stakeholder

`o v1 ainda funciona, não quebra nada agora` → `Version 1.x remains backward compatible. The breaking changes are scheduled for version 2.0.0, which will be released on March 31, 2027.` (remains + scheduled for + future release)

Observe como voz passiva, modal verbs e datas concretas transformam cada mensagem em uma comunicação clara para o consumidor.

Resumo

Comunicação profissional de mudanças em APIs em B2 combina voz passiva (the endpoint has been removed, the field has been renamed), modal verbs de recomendação (we recommend, please update, you should), noun clauses (we recommend that you upgrade) e participle clauses (following our deprecation policy, …). O vocabulário-chave é breaking change / non-breaking change / backward compatibility / deprecation / sunset date / migration guide / contract testing / consumer-driven contract, e o princípio central é sempre combinar a mudança com a data, a razão e a ação esperada do consumidor.

História: APIs públicas e breaking changes

Nível: B2

História em inglês

The deprecation meeting

On Monday morning, Sara, who leads the platform team at a fintech, opened the deprecation ticket she had been avoiding for two months. The /v1/charges endpoint, which handled the bulk of the company's payment traffic, was officially being deprecated. Following the company's deprecation policy, the endpoint would be sunset six months after the announcement. That meant the sunset date was September 30, 2026, exactly the day her manager had asked her to plan around. Sara opened a blank document and typed, "Migration guide: /v1/charges to /v2/charges."

What changed in v2

The first thing she wrote was a one-line summary of every breaking change in v2. The `currency` field had been renamed to `iso_currency` to align with the ISO 4217 standard. The response now wrapped the charge object in a `data` envelope, which made room for pagination metadata. The default page size had been increased from 20 to 50, which was a non-breaking change for most consumers. The `customer_id` field had been made optional, since the new external system could resolve the customer from the API key.

Talking to the consumers

Before she published the guide, Sara scheduled a call with the largest consumer of the API, the e-commerce team. She wanted to be sure that no breaking change had been missed, because the contract test had only run against a small sample of requests. On the call, the e-commerce lead said, "We strongly recommend that you keep the v1 path alive for at least eight months, not six." Sara took the feedback, but she did not promise anything yet, since the sunset date had already been communicated to the board. After the call, she updated the contract test to cover every endpoint the e-commerce team actually used.

The announcement email

On Friday, Sara sent the announcement email that she had been drafting all week. The subject line read, "[Action required] /v1/charges deprecation — sunset on September 30, 2026." She listed every breaking change, the sunset date, the link to the migration guide, and the office hours for questions. She also reminded consumers that the v1 endpoint would still respond, but a `Deprecation: true` header would be added to every response. By Sunday evening, three of the four consumers had replied with a migration timeline, and the fourth had booked office hours. Sara closed the ticket, and the v1 endpoint continued to serve traffic until its sunset, six months later.

Tradução linha por linha

Notas de vocabulário

• the deprecation ticket she had been avoiding = past perfect continuous: ação que vinha acontecendo antes de outra no passado
• Following the company's deprecation policy = participle clause inicial: introduz a base normativa para a decisão
• had been renamed to iso_currency = past perfect passiva: mudança já feita antes de outra ação no passado
• wrapped the charge object in a data envelope = wrap + object + in + envelope: descrever mudanças de formato de resposta
• which was a non-breaking change = non-defining relative clause: informação extra sobre o aumento de page size
• had been made optional = passiva com make + optional: descrever mudança de obrigatoriedade de campo
• we strongly recommend that you keep the v1 path alive = strongly recommend + that + you + verbo base: recomendação enfática em noun clause
• she did not promise anything yet = did not promise + yet: negar compromisso imediato sem fechar a porta
• Deprecation: true header would be added = would be added (passiva futura no passado): mudança que estava planejada para acontecer
• [Action required] = prefixo padrão de email técnico que exige ação do consumidor; chama atenção sem ser alarmista

Perguntas de compreensão

1. What was Sara's role at the company?
2. Which endpoint was being deprecated, and what was the sunset date?
3. How long was the deprecation notice period in Sara's company?
4. What was the first thing Sara wrote in the migration guide?
5. Name two breaking changes that Sara listed for v2.
6. Why did the e-commerce team recommend keeping v1 alive for eight months instead of six?
7. What did Sara do after the call with the e-commerce team?
8. What was the subject line of Sara's announcement email?
9. What did Sara remind consumers about the v1 endpoint during the deprecation period?
10. How did the announcement email work out?
11. What happened to the v1 endpoint in the end?

Prática com a história

1. Reescreva em tom de release note: tirei o /v1/charges ontem sem avisar
2. Reescreva como migration guide: clientes precisam trocar `currency` por `iso_currency` no body
3. Traduza: Recomendamos fortemente que vocês mantenham o caminho v1 ativo por pelo menos oito meses.
4. Reescreva com participle clause inicial: Sara seguiu a política de deprecation. O endpoint será desativado em seis meses.
5. Reescreva usando present perfect passiva: renomeamos o campo `currency` para `iso_currency` antes da release