Pular para o conteúdo

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

Você muda um campo na API e o app antigo, ainda instalado em milhares de celulares, quebra. Veja como evoluir APIs sem derrubar ninguém.

Por Roger C. Ribeiro, fundador da Wecodex3 min de leitura

Você muda um campo na API e o app antigo, ainda instalado em milhares de celulares, quebra. Veja como evoluir APIs sem derrubar 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: menos bugs em produção).

Comece certo

Convenções claras desde o início reduzem a necessidade de quebrar contratos depois (API REST: boas práticas de nomes, status codes e paginação). 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).

Se a sua API atende um aplicativo, vale ver como funciona o desenvolvimento de aplicativos para empresas, onde versões antigas continuam instaladas por meses.

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

  • APIs
  • Versionamento
  • Backend
  • Apps
CompartilharWhatsAppLinkedIn

Escrito por

Roger C. Ribeiro

Fundador da Wecodex. Escreve sobre engenharia de software, performance, APIs, segurança e IA aplicada a empresas.

Serviços relacionados

Resolver de vez, com quem faz isso todo dia

Precisa de uma API ou integração que não caia quando o negócio crescer?

Este artigo mostra o caminho. A implementação sob medida, o detalhe que muda o resultado no seu caso, é o trabalho da Wecodex, empresa de engenharia do grupo Wocom.