Tecnologia e Infraestrutura → Versionização API

Versionização da API

1) Por que é necessário

• reduz o risco de incidentes nos lançamentos,
• permite introduzir melhorias e segurança programadas,
• dá aos negócios um prazo previsível para a migração de parceiros.

2) Classificação de alterações

PATCH (não quebra): correções sem alteração de contrato (adição de campos opcionais, gravações de validação).
MENOR (Extension): back-compatível extensões (novos endpoint, campos default).
MAJOR (quebra): altera a estrutura, semânticos ou remove campos/endpoint.

Recomendado por SemVer 'MAJOR. MINOR. PATCH 'para artefatos (SDK/circuitos), e o número «externo» da API pode ser simplificado (v1, v2).

3) Modelos de versionização REST

1. EM URI:

`GET /v1/payments/{id}`

Os benefícios são transparentes, armazenáveis, fáceis de rotar. Contras: duplicação de documentação, mais difícil de evoluir sutilmente.

2. Em cabeçalhos (conteúdo negotiation):

`Accept: application/vnd. company. payments. v2+json`

Vantagens: flexibilidade, falta de «lixo» no URL, evolução conveniente do midiatip. Contras: É mais difícil de usar no navegador, precisa de um cliente disciplinado.

3. No cabeçalho:

`X-API-Version: 2` (или `Api-Version: 2025-09-01`)

Os benefícios estão apenas na entrada. Contras: Sem padrão, cuidado com o dinheiro.

4. Versão-data (data-based):

Bom para fintechs/relatórios: «cortes» previsíveis de mudanças (por exemplo, trimestrais).

5. Versionização do recurso/modelo:

Recomendação: para integrações externas - 'URI vN' + Deprecation/Sunset Títulos; para os internos - você pode 'Accept' ou o cabeçalho da versão, se o gateway e a plataforma suportarem isso.

4) GraphQL

Preferência - sem versões globais. Evolução por adição de campos/tipos e despricagem ('@ deprecated (reason: «...)»).
Mudanças quebrantes - apenas em «grandes» janelas (versioned schema namespace) com hide migratório.
Siga «n + 1» e não altere os campos existentes.

5) gRPC / Protobuf

Os números de campo são inalterados. Selecione os campos remotos como 'reserved'.
Adicione os campos como optional com default seguro.
Use o buf breaking/lint para verificar automaticamente a compatibilidade.
Versionize pacotes/plug-ins: 'package payments. v1;` → `payments. v2`.

6) API de evento (EDA)

O esquema é o mesmo contrato. Mantenha-a em Schema Registry (Avro/JSON-Schema/Protobuf).
Os topics e versões são 'payments. v1. authorized`, `payments. v2. authorized`.
As alterações de quebra são um novo tipo de evento ou um novo top.
Garantia de evolução: backward-compatível para consumeiros durante o período LTS.

7) Política de Despricagem e EOL

• Deprecation: marcas em changelog e especificações (OpenAPI/GraphQL SDL), cabeçalho
• 'Deprecation: true' e quando possível 'Sunset: Tue, 31 Mar 2026 00:00:00 SE'.
• Comunicações: email/portal do parceiro, notificações webhooks, notas release.
• Prazo: MENOR - 3 a 6 meses de suporte, MAIOR - 9 a 18 meses (dependendo das críticas).
• Janelas de tempo: fixe na «Política de versionização da API».

8) Rotação e lançamentos

API Gateway (Kong/Apigee/Nginx/Envoy): regras para prefixo '/v1/', para cabeçalho ou mediatipo.

if ($http_accept ~ "vnd.company.payments.v2") { proxy_pass http://payments-v2; }

Canary/Blue-Green/Shadow: Role a nova versão em 1% a 5% do tráfego, compare métricas e logs de erros contratuais.
Função Flags: Escondemos o comportamento sem alterar o contrato.
Migração zero-downtime: com o MAJOR, forneça dupla gravação/leitura (dual-write/read) do esquema de dados.

9) Contrato-teste e controle de compatibilidade

OpenAPI Diff (ou swagger-diff) - verifique se MINOR/PATCH não está quebrando esquemas.
Espectral linting - estilo, metadados obrigatórios (versão, Deprecation).
Consumer-Driven Contracts (Pact) - garante que o provedor não quebra clientes.
buf breaking для protobuf.
O CI deve cair em alterações de quebra sem aumento do MAJOR.

10) Documentação e SDK

Versionize spacks: '/docs/api/v1/openapi. json`, `/docs/api/v2/…`.
Gere SDK em versões (npm/maven/pypi) com SemVer e changelog.
Assinale métodos obsoletos em anotações SDK/Deprecated.

11) Observabilidade em versões

• RPS/latência/erro de versão ('api _ versão' editora).
• Mapas de uso de endpoint: quem mais em v1?
• Alerts: «> 10% 4xx due to contract mismatch», «clientes antigos> X% após a data T».

12) Em dinheiro e versões

A versão no caminho melhora a capacidade de armazenamento do CDN.

• `Vary: Accept, X-API-Version`.
• Não altere a semântica de resposta do MENOR para quebrar chaves de kesh.

13) Segurança

Não criptografe ou encarte a versão no JWT - a versão define o pedido, não o token.
Não abra números internos de montagens. Use «v1/v2» em mensagens externas.
No MAJOR, reveja a validação, os limites, a camuflagem PII.

14) Migrações e assistentes automáticos

Publique «Migration Guide v1 → v2»: tabela de correspondência de campos, exemplos de solicitação/resposta, edge-mala.
Oferece lentes para clientes (CLI) que realçam campos obsoletos.
Para grandes parceiros - sandbox com duas versões e dataset.

15) Anti-pattern

«V1 eterno»: falta de deadline e métricas de uso.
Alterações quebrantes ocultas em MENOR/PATCH.
Versão em query string ('? v = 2') - Quebra o dinheiro e a leitura.
«Um endpoint - cem valores de bandeira»: difícil de testar/documentar.

16) Folha de cheque de implementação

1. O modelo selecionado (URI/Aceitt/Header) é para clientes externos e internos.
2. SemVer para especificações e SDK, breaking-check-up automático em CI.
3. Deprecation/Sunset política e modelos de comunicação.
4. Gateway Rotation + canários, dashboards em versões.
5. CDC/Contracto testes de integração crítica (pagamentos, KYC, relatórios).
6. Documentação/SDK/guia de migração publicado ao mesmo tempo que o lançamento.
7. Um plano EOL com datas e responsáveis.

17) Exemplos

17. 1 REST (URI + títulos)

GET /v2/withdrawals/12345
Accept: application/json
Idempotency-Key: 4a1c-…-9f

json
{
"id": "12345",
"status": "PENDING_REVIEW",
"amount": {"value": "100.00", "currency": "EUR"},
"limits": {"daily": "500.00"},
"created_at": "2025-10-02T10:00:00Z",
"links": [{"rel": "cancel", "href": "/v2/withdrawals/12345/cancel", "method": "POST"}]
}

Deprecation: true
Sunset: Tue, 31 Mar 2026 00:00:00 GMT
Link: </v2/docs>; rel="successor-version"

17. 2 Conteúdo Negotação (midiatip)

GET /payments/987
Accept: application/vnd.company.payments.v2+json
Vary: Accept

17. 3 GraphQL (despricagem do campo)

graphql type Payment {
id: ID!
amount: Money!
status: PaymentStatus!
method: PaymentMethod!
legacyCode: String @deprecated(reason: "Use field `method`")
}

17. 4 gRPC (protobuf)

proto package payments.v2;

message Withdrawal {
string id = 1;
Money amount = 2;
string status = 3; // previously enum, now string with documented values reserved 4; // legacy field removed in v1 -> v2
}

17. 5 Modelo de evento

• `wallet. v1. balance. updated`
• `wallet. v2. balance. changed '(novo evento com esquema avançado)

Os circuitos estão armazenados na Registry, e a produtora não publica nenhum evento com esquema de compatibilidade.

18) Contexto iGaming/fintech (prática)

Pagamentos: entrada v2 para novos PSP, onde 'status '/' decline _ reason' foi expandido; na entrada de mapping v1 → v2 para relatórios.
KYC: MENOR adiciona o campo 'pep _ screening', os clientes v1 ignoram, v2 - exige.
Jogos/limites responsáveis: MAJOR altera o modelo de limites (diárias/semanais). Exportar duplamente para relatórios antes do EOL v1.
Relatórios aos reguladores: versões-data fixas: 'reporting-2025-01'.

19) Mini-política (exemplo para wiki)

Modelo: para API externa - 'URI/ vN/'; para os internos - 'Accept:... vN+json' ou 'X-API-Versão: N'.
SemVer: especificações e SDK são publicadas como 'N. minor. patch`. O MAJOR exige RFC/ADR.
Compatibilidade MENOR/PATCH - sem alterações de quebra. Quebra de → só através do MAJOR.
Deprecation/EOL: anúncio de ≥90 dias; Data sunset em cabeçalho; Ramo LTS para clientes críticos.
Controle: OpenAPI diff/buf breaking em CI, CDC para integrações essenciais.
Observabilidade: métricas/logs com a editora «api _ version».
Lançamentos: canary 5% ≥ 24h, seguido por etapas de 100% em métricas verdes.

Resultado

Versioning não é sobre «/v2 em URL », mas sobre o processo: regras de evolução explícitas, verificações automáticas de compatibilidade, lançamentos controlados e respeito à integração. Digite uma política compreensível, automatize o controle e a observabilidade - e as mudanças deixarão de ser uma ameaça para o produto.