Versionamento de API na prática

O problema

Muita equipe só lembra de versionamento quando já quebrou alguém.

Enquanto a API esta pequena, mudar contrato parece barato. A aplicação consumidora muda junto, todo mundo conhece todo mundo e o time conclui que “depois a gente organiza isso”.

O problema aparece quando o cliente já esta em produção, existe app mobile preso em release antiga, parceiro externo consome o endpoint e uma pequena mudança quebra checkout, integração ou tela real.

Versionamento entra justamente quando mudar sem pensar deixa de ser opcao.

Modelo mental

Versionar API não e um ritual sobre número de versão.

E uma disciplina para responder esta pergunta:

como eu evoluo o contrato sem surpreender quem depende dele?

Isso leva para tres ideias mais uteis do que decorar estratégias:

1. Compatibilidade primeiro. Se eu consigo evoluir sem quebrar, melhor.
2. Mudança breaking precisa de transição. Quebrar pode ser necessário, mas não deveria ser surpresa.
3. Cada versão extra custa manutenção. Ter duas ou tres versões convivendo não e gratis.

Quebrando o problema

O que normalmente e compativel

Mudancas que muitas vezes sao seguras:

• adicionar campo opcional na resposta
• adicionar novo endpoint
• aceitar parametro novo opcional
• expandir valor suportado sem mudar significado antigo

Essas mudancas costumam ser menos perigosas porque clientes antigos continuam entendendo o contrato como antes.

O que costuma ser breaking

Mudancas perigosas:

• remover campo
• renomear campo
• mudar tipo de dado
• mudar obrigatoriedade
• mudar semântica de retorno
• trocar status code esperado sem transição

O problema aqui não e só técnico.

E de expectativa quebrada.

Quando criar nova versão faz sentido

Nova versão faz mais sentido quando a mudança importante não cabe numa evolução compativel.

Exemplos:

• modelo de recurso mudou de forma significativa
• autenticação ou semântica de erro mudaram de forma profunda
• cliente antigo realmente não consegue continuar sem adaptacao

Mas criar versão nova toda vez que bate desconforto vira fuga, não estratégia.

Onde versionar

Pode aparecer em lugares diferentes:

• URL, como /v2/orders
• header
• media type
• schema ou contrato em gateway interno

O ponto principal não e a moda do formato.

E a clareza operacional:

• o consumidor entende o que esta usando?
• você consegue observar quem ainda esta na versão antiga?
• a migração fica clara?

Exemplo simples

Imagine um endpoint:

GET /orders/123

Resposta antiga:

{
  "id": "123",
  "status": "paid",
  "total": 150
}

Agora o time quer expor moeda e itens.

Uma evolução compativel seria:

{
  "id": "123",
  "status": "paid",
  "total": 150,
  "currency": "BRL",
  "items": []
}

Cliente antigo continua funcionando.

Agora imagine que alguém quer trocar total de número para objeto:

{
  "total": {
    "amount": 150,
    "currency": "BRL"
  }
}

Isso tende a ser breaking.

Aqui você precisa de transição:

• adicionar campo novo primeiro
• marcar antigo como deprecated
• medir uso
• combinar janela de migração
• remover depois com previsibilidade

Perceba que o ponto forte não e “inventar v2”. E desenhar a convivência.

Erros comuns

• Criar versão nova para qualquer ajuste pequeno.
• Mudar contrato silenciosamente porque “internamente era fácil”.
• Esquecer que app mobile e parceiro externo nem sempre atualizam no mesmo ritmo.
• Manter versão antiga para sempre sem plano de aposentadoria.
• Versionar caminho, mas não versionar comportamento de verdade.

Como um senior pensa

Quem tem mais experiência olha para versão como custo de produto e operação, não só como detalhe de rota.

O raciocínio costuma ser:

“Se eu consigo evoluir de forma compativel, melhor. Se não consigo, preciso tornar a transição observável, comunicada e temporária.”

Essa postura evita dois extremos:

• quebrar cliente por arrogancia
• carregar legado eterno por medo

O que o entrevistador quer ver

Em entrevista, o avaliador quer ver se você pensa em contrato como compromisso real.

Sinaliza maturidade quando você:

• diferencia mudança compativel de breaking
• fala de depreciação e coexistencia
• menciona observabilidade para saber quem ainda usa a versão antiga
• evita tratar /v2 como unica resposta possível

Uma resposta forte costuma soar assim:

“Eu tentaria evolução compativel primeiro. Se a mudança for breaking de verdade, eu criaria uma transição explicita, mediria consumo da versão antiga e daria janela de migração antes de remover.”

Versionamento bom não protege só o servidor. Protege a confiança entre quem oferece e quem consome o contrato.