Versionamento de API: mudar sem quebrar o app de ninguém

No site, você publica a nova versão e todos passam a usá-la. No app, não: há usuários com versões de meses atrás que continuarão chamando a sua API do jeito antigo. Parceiros integrados também. Mudar o contrato sem cuidado quebra todos eles.

Mudanças que não quebram

• Adicionar um campo novo na resposta.
• Adicionar uma rota nova.
• Aceitar um parâmetro opcional.

Mudanças que quebram

• Remover ou renomear campos.
• Mudar o tipo de um campo.
• Tornar obrigatório o que era opcional.
• Mudar o significado de um valor.

Estratégias

1. 1.Evite quebrar: adicione o campo novo, mantenha o antigo por um tempo, marque-o como obsoleto.
2. 2.Versão na URL (/v1/pedidos, /v2/pedidos) para mudanças grandes.
3. 3.Prazo de desligamento comunicado e monitorado: só desligue a versão antiga quando o uso estiver próximo de zero.
4. 4.Versão mínima do app: forçar atualização para versões muito antigas, com uma tela amigável.

Tipos ajudam

Com tipos compartilhados entre app e API, mudanças incompatíveis aparecem na compilação (TypeScript de ponta a ponta: reduzindo bugs em produção com tipagem unificada entre front, app e back).

Comece certo

Convenções claras desde o início reduzem a necessidade de quebrar contratos depois (API REST bem desenhada: nomes, status codes e paginação que não confundem ninguém). E registre quais versões estão sendo usadas, com logs e métricas (Logs estruturados: encontre o erro em minutos, não em horas).

A We Codex constrói APIs para apps e parceiros em sistemas web. Fale com a gente.