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.Evite quebrar: adicione o campo novo, mantenha o antigo por um tempo, marque-o como obsoleto.
- 2.Versão na URL (
/v1/pedidos,/v2/pedidos) para mudanças grandes. - 3.Prazo de desligamento comunicado e monitorado: só desligue a versão antiga quando o uso estiver próximo de zero.
- 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
Escrito por
Roger C. RibeiroFundador 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.
Continue lendo
Tudo sobre Backend & APIs- Ler artigo
Backend & APIs3 min
API REST: boas práticas de nomes, status codes e paginação
Rotas como /getUsuarios2, erro 200 com "success: false" e listas sem paginação. Veja as convenções que tornam uma API REST fácil de usar e de manter.
- Ler artigo
Backend & APIs3 min
TypeScript de ponta a ponta: menos bugs em produção
O backend muda um campo e o app quebra em produção. Tipos compartilhados entre front, app e API acabam com essa classe inteira de bugs.
- Ler artigo
Backend & APIs3 min
Logs estruturados: encontre o erro em minutos, não em horas
Um cliente reclama de um erro de ontem e o time passa a manhã procurando no meio de milhões de linhas de texto. Logs estruturados resolvem isso.