API compatível com atualizações
1) Princípios básicos de compatibilidade
Aditivo-first: Adicione um novo sem quebrar o antigo (novos campos opcionais/endpoint, novos valores enum).
Contratos estáveis: «O que a especificação promete é que funciona»; o comportamento está documentado.
Backward> Forward: prioridade da compatibilidade reversa; forward é permitido através de tolerant-readers.
Os documentos são primários: a única fonte de verdade é a versão do circuito em OpenAPI/AsyncAPI/Proto.
Uma evolução clara: breaking - apenas através da nova versão major e guia migratório.
2) Taxonomia de alterações
2. 1 Compatíveis (MENOR/PATCH)
Adicione campos/headers opcionais, novos endpoint, query-parâmetros com default.
Aumentar os limites ('page _ size', TTL), especificar os erros sem alterar o código/semântica.
Adicione os valores enum se os clientes ignorarem «desconhecidos» (tolerant-reader).
2. 2 Ambíguos (Behavioral)
Alterar os incumprimentos, a ordem de ordenamento, os times finos, as quotas, pode «quebrar» a lógica dos negócios. Requer RFC + anúncio e canarinhos.
2. 3 Quebrantes (MAJOR)
Renomear ou remover campos, alterar o tipo/formato, substituir códigos de erro, ou não compatibilizar contratos/esquemas de autenticação.
3) Política de versionização
Estratégia: 'path versioning' ('/v1 ', '/v2').
Menor/patch, «adiciona, não quebra».
Títulos datados de 'X-API-Versão-Data' para alterações graduais suaves.
Tipos de mídia (opz.) : `Accept: application/vnd. acme. v1 + json 'para granulação fina.
4) Depressões e sunset
4. 1 Cabeçalhos de comunicação
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Ordem de saída
1. Anúncio no portal/correio/SDK release notas.
2. A janela de alerta ≥ 90 a 180 dias.
3. Estatais em dashbord adopção.
4. Após sunset - 410 Gone ou «read-only» modo para o período grace, se concordado.
5) Migração e coexistência de versões
Dual-write/dual-read durante o período de transição e relatórios.
Adaptadores (temporários): gateway conversões de payload antigo → novos circuitos; A vida do adaptador é limitada.
Ajuda SDK: lançamentos que suportam ambas as versões com avisos de despreceção (1 vez por processo).
Bandeiras fichas: nova semântica incluída na lista de chaves/tenantes.
6) Backward e forward compatibilidade
6. 1 Backward (clientes antigos ↔ novo servidor)
Não alterar formatos de tipo/obrigatoriedade.
Os novos campos são apenas opcionais.
Erros são antigos 'error _ código', novos códigos adicionar, não substituir.
6. 2 Forward (novos clientes ↔ servidor antigo)
Verificar a disponibilidade (capabilities) de OPÇÕES//versões.
Grace-comportamento: o cliente deve tolerar as fichas ausentes.
7) Contratos e verificações automáticas
Registry: armazenando versões dos circuitos; Os difas PR → relatórios «breaking/non-breaking».
Linter: nomes/tipos, idempotidade, paginação, códigos estáveis.
CDC (Consumer-Driven Contracts): testes de integradores em CI provedor (Pact e similares).
Gate: PR bloqueado por breaking sem 'major bump '/RFC.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Lançamento de canário e marcha de volta
Canary: 10% → 25% → 50% → 100% do tráfego; auto-recall quando o SLO piora (5xx/latency/429).
Chave beta: acesso a novas versões por allowlist.
Release freeze: ao queimar error-boodget.
Analista de aceitação: participação do tráfego/clientes na nova versão, tempo de migração.
9) Compatibilidade em detalhes: erros, paginação, idempotidade
9. 1 Erros
Não altere status HTTP nos cenários existentes.
'erro _ código' é estável; os novos códigos são apenas adicionar.
'aplicação/projem + json' é um formato único.
9. 2 Paginação
Ir para cursor/keyset = MENOR se estiver suportado o antigo 'offset/limit'.
Documente a triagem '(updated _ at, id)' e a estabilidade do cursor.
9. 3 Idempotency
Para write, 'Idempotency-Key' + '409 IDEMP _ REPLAY' em um conflito.
As migrações não devem alterar a semântica de idempotidade.
10) Transformação Gateway (quando apropriado)
Map v1→v2 campos, normalizar erros, converter formatos de data/dinheiro.
Guardrails: as transformações são transparentes e logadas; não esconda breaking, mas use como ponte com prazo limitado.
11) Comunicações e portal
Changelog с датами (`added/changed/deprecated/removed/fixed`).
Cartão de versão: status (beta/GA/deprecated), data sunset, links de guindaste.
Webhooks de notificação: 'deprecation. notice`, `version. released`, `plan. change`.
SDK release notas + banner no portal.
12) Métricas de sucesso
Adition rate v2 (por solicitação/cliente).
Backward-compat invidents («quebra»).
Error mix (participações 4xx/5xx/429) antes/depois do lançamento.
Time-to-Adopt mediana.
Suporte load (tíquetes/ned).
Costa-to-Serve (custo de infraestrutura por chamada).
13) Modelos e exemplos
13. 1 Títulos de versões e depredações
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Políticas de versão (fatia YAML)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. 3 OpenAPI: adição de campo compatível
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) Folha de cheque de lançamento (MENOR/MAIOR)
MINOR
- DIFF: não-breaking, linter verde
- Documentação/SDK atualizados (exemplos/codecs)
- Canário + revezamento de carro SLO
- Plano comm, página no portal
- Adopção de dashboards e erros
MAJOR
- RFC/ADR, data sunset e janela ≥90 -180 dias
- Ponte v1↔v2 (gateway) e guia migratório
- Dual-write/read e cruzamento
- SDK com ambos os API + avisos
- Piloto com integradores-chave
15) Plano de implementação (3 iterações)
1. Fundações (2 semanas):
Registry circuitos, lente e auto-diff em CI; política de compatibilidade; Títulos de «Deprecation/Sunset».
2. Lançamentos controlados (3-4 semanas):
Canarinhos, bandeiras fichas, alertas SLO; portal de versões; Lançamentos SDK com suporte de 2 ramais.
3. Automação e zoom (contínuo):
Testes CDC de consumidores em CI, previsão sunset de tendência de adopção, notação automática e lembretes.
16) Mini-FAQ
É possível alterar o tipo de campo sem o maior?
Não. Até «stroka→chislo» é breaking. Digite o novo campo, o antigo é deprecate.
Enum: pode adicionar valores?
Sim, se os clientes forem tolerant-readers. Senão, primeiro alerta e beta.
Quanto tempo para manter a versão antiga?
Até agora, a adupção é nova% e a janela de depredação está intacta. Fixe o prazo na política.
Resultado
A API é uma disciplina: abordagem aditiva, esquemas formais e difas, lançamentos canários, depredações claras e migrações controladas. Mantenha a política de mudanças, automatize as verificações e comunicações, mede a adopção - e as suas atualizações deixarão de quebrar clientes e aumentarão a taxa de evolução sem perder a confiabilidade.