Não é incomum encontrar endpoints como /instagram/perfil e /instagram/perfil-v2 coexistindo. Isso não é acidente — é uma prática deliberada de design de API.
Por que uma API cria uma versão nova em vez de alterar a existente
Mudar o formato de resposta de um endpoint existente quebraria qualquer integração já em produção que dependa do formato antigo. Lançar uma versão nova, mantendo a antiga funcionando, dá tempo para cada cliente migrar no seu próprio ritmo.
O que costuma mudar entre versões
- Novos campos adicionados à resposta;
- Estrutura de dados reorganizada (ex: campos agrupados em objetos aninhados);
- Correção de inconsistências identificadas na versão anterior.
Estratégia recomendada pra quem consome
Ao integrar um endpoint novo, prefira sempre a versão mais recente disponível — evita ter que migrar logo depois. Para integrações antigas, planeje a migração quando a documentação sinalizar que uma versão anterior vai ser descontinuada, em vez de deixar pra última hora.
