Estratégias de versionização da API

Por que precisa de versionização

A API muda mais rapidamente do que os clientes. A versionização permite a produção de fichas e a correção de erros sem falhas de integração, define o ritual de mudanças e torna a evolução previsível. Chave: alterações aditivas padrão, majors - apenas para quebra, verificações automáticas de compatibilidade e políticas sunset elaboradas.

Princípios básicos

1. Aditivo-first: novos campos/métodos/eventos opcionais - ok; remoção e alteração de significado - maior.
2. O MGC (contrato mínimo de garantia) está estável; enriquecimento - através de capabilities/'? incluse = '.
3. Tolerant reader: Os clientes ignoram campos desconhecidos e sobrevivem corretamente às extensões do enum.
4. Semantic Versioning: `MAJOR. MINOR. PATCH 'para artefatos, SDK e eventos.
5. Automate: schema-diff, linteres e testes CDC bloqueiam alterações breaking.

Onde armazenar versão (mecânicos de direcionamento)

REST/HTTP

Versão URI: '/v1/orders '→ apenas routar, confortavelmente em passarelas. Menos - «apagar» a evolução das representações.
Midiatip/cabeçalho: 'Accept: aplicação/vnd. example. orders. v1 + json '- controle exato do formato; É mais difícil de fazer.
Versão query: '? api-versão = 1' - conveniente para A/B, mas fácil de perder em cajas/logs.
Recomendação: URI para as linhas major + função/capability flags e conteúdo-negacionado para extensões menores.

gRPC / Protobuf

Pacotes/serviços: 'package payments. v1; service PaymentsV1; '- linhas claras.
A numeração de formatação está inalterada; marcas de formatação remotas não podem ser reutilizadas.
Novos campos - 'optional'; breaking → novo '.v2'.

GraphQL

Esquema sem major explícito no URL. Evolução através de @ deprecated e janelas de migração; O maior é um novo esquema de endpoint.
Controlar complexity/depth faz parte do contrato.

Event-driven (Kafka/NATS/Pulsar)

O nome do evento é 'payment. authorized. v1 'é uma versão do tipo.
Registro de esquema (Avro/JSON Schema/Protobuf) com modos de compatibilidade (BACKWARD/FORWARD/FULL).
Major → dual-emit 'v1' e 'v2' por um período de transição.

Modelo de versão e política de alterações

Semantic Versioning

MAJOR - Alterações quebrantes: remoção/renomeamento de campos, mudança de chaves de partilha, outro significado de estatais, validação mais rigorosa.
MENOR - Adutoras: novos campos opcionais/endpoint/eventos, novos valores enum para tolerant-reader.
PATCH - correções sem alteração de contrato e semântica.

Deprecation & Sunset

Marcar obsoleto ('Deprecated: true', '@ deprecated'), publicar uma data sunset, alternativa e migração.
Em HTTP, títulos de «Sunset», «Deprecation»; em eventos - individual '.deprecation. notice`.
Conduza a telemetria usage para decidir sobre a retirada.

Estratégias de versões por estilo

REST

Linhas Maiores em/v1 ,/v2.
MENOR: extensão dos circuitos, '? fields =', '? incluse ='; extensões enum seguras.
ETAG/If-Match e Idumpotent POST para coerência sem quebra.
Erros - Formato estável ('tipo', 'código', 'trace _ id').

gRPC

Introduza novos serviços/métodos para quebrar: 'PaymentsV2. Capture`.
Os estados de erro e a semântica deadline fazem parte do contrato; alteração → novo método/serviço.
Use a linha de mensagens e não a mude para menor.

GraphQL

Adicione campos e tipos livres; remoção através de '@ deprecated' + janela de migração; grande redisine → novo esquema ('/graphql-v2 ').
Introspecção e descrições - must-have para a migração de clientes.

Events

Core vs enriched: o núcleo é estável, o enriquecimento vive perto e é versionizado separadamente.
A chave de partilha está inalterada dentro da linha maior.
Migração Major - 'dual-emit' + migração de projeções/consoadores.

Negotion e capability-bandeiras

Capabilities: o cliente envia 'X-Capabilities: risk _ score, price _ v2'; o servidor responde com uma representação avançada.
Preferer (HTTP) e "hints' para respostas parciais.
Em socks/striptease, uma mensagem handshake com uma lista de extensões suportadas.

Lançamento de versões maiores sem dor

1. RFC/ADR: Por que você precisa de um major que está quebrando, matriz de risco.
2. Dual-run: lançamento paralelo de 'v1' e 'v2' (publicação dupla de eventos, dois gateway roots, espelhamento de tráfego).
3. Adaptadores de migração proxy/translatores 'v1↔v2' para clientes pesados.
4. Canário: por grupo de clientes/topics/marcas em gateway.
5. Plano sunset: datas, comunicações, estandes, dados de teste, monitoramento do uso.

Os papéis da plataforma e da infraestrutura

API Gateway/Service Mesh: roteiro em versão, cabeçalhos, caminhos; rate-limit и auth per-version.
Schema Registry & Catalog: Fonte de verdade para speck/diagramas com histórico de difs.
CI/CD: линтеры (Spectral, Buf), schema-diff (OpenAPI-diff, Buf breaking), CDC (Pact).
Observabilidade: a versão deve entrar em logs/trailers/métricas.

Teste de versões

Schema-diff em PR: bloquear breaking.
Consumer-Driven Contracts: O provedor é testado contra contratos de consumidores reais.
Golden sample: respostas de referência para versões.
E2E-canário: comparação p95/p99, erros e temporizações entre as versões.
Replay para eventos: as projeções são repetidas para v2 sem discrepâncias.

Migração de dados e bases de dados

Para REST/gRPC: as migrações de BD são coordenadas por meio de «expand-and-contract» (adicione uma coluna → comece a escrever → alterna a leitura → afaste a antiga).
Para Events: dual-emit e migração de consoadores; às vezes, reaproximar o loga para novas projeções.
Não façam «grandes explosões».

Relação de segurança

Scopes per version: individuais OIDC-scopes/papéis para v1/v2.
Segredos/claim's token - parte do contrato; o seu turno = major.
PII/PCI - Não estenda o payload sem necessidade; novos campos - com o mínimo de privilégios.

Antipattern

Swagger-wash: especificação atualizada, servidor não (ou vice-versa).
Reutilizar as marcas protobuf é um estrago silencioso de dados.
Mudança de sentido enum sem maior.
Global '/v2 'por cosméticos, versão sem quebra.
Esqueceu-se de sunset/usage-métricas: não é possível remover a versão antiga de forma segura.
Um top comum para diferentes maiores é misturar ordem e chave.

Folha de cheque antes do lançamento

• As alterações são aditivas ou uma linha maior diferente foi preparada.
• Linteres e schema-diff verdes (breaking não passou).
• SDK/exemplos/documentação atualizados, notas de rodapé sobre compatibilidade.
• Ativado tolerant reader nos clientes; enum-fallback testado.
• Para major - plano dual-run, adaptadores, canário, datas sunset e correio.
• As métricas/logs/trailers contêm a versão e a segmentação.
• Há um estande e kits golden para comparar v1↔v2.
• Para eventos - registro de esquema no modo BACKWARD/FULL, as chaves de partilha estão inalteradas.

Exemplos de modelos

REST (URI + negotiation)

Rota: '/api/v2/orders/se

Заголовок: `Prefer: include=items,customer`, `X-Capabilities: risk_score`

Deprecation: `Sunset: 2026-06-30`, `Link: ; rel="alternate"`

Protobuf/gRPC

proto package payments.v2;

service PaymentsV2 {
rpc Capture (CaptureRequestV2) returns (CaptureResponseV2);
}

Events

`payment. captured. v2 '(núcleo) e' payment. enriched. v2 '(peças).
Durante o período de transição, a produtora vai «v1» e «v2».

FAQ

Quando precisas de «/v2 »?
Quando os invariantes/semânticos mudam, os campos/métodos são removidos, o formato dos identificadores é alterado, a chave de partilha, o SLA/timing para que os clientes sejam quebrados.

Podemos viver sem uma versão explícita no REST?
Só para sistemas pequenos. Para as integrações externas, as linhas maiores aparentes são melhores.

Qual o prazo para manter a versão ultrapassada?
Depende do ecossistema. Para parceiros externos, normalmente 6-12 meses com aviso precoce e canário.

Em que a versionização de eventos difere da API?
Eventos - append-only; nova semântica = novo tipo '.v2' e dual-emit. A chave de partilha faz parte do contrato.

Resultado

As estratégias de versioning são um processo e ferramentas: evolução aditiva padrão, linhas de maior clareza, capability-negotion, dual-run e sunset. Adicione as verificações automáticas de compatibilidade, telemetria de uso e disciplina de documentação - e suas APIs vão evoluir rapidamente, sem «migrações noturnas» e baixas inesperadas nos clientes.