Versionamento API: 13 boas praticas para compatibilidade

Versionar uma API não é apenas adicionar um número na URL. É um processo de comunicação entre quem fornece e quem consome. Quando você altera contratos, precisa garantir que clientes existentes não quebrem. Estas 13 boas praticas ajudam a equilibrar evolução e estabilidade.

O versionamento de API é a pratica de gerenciar alterações na interface de forma transparente, permitindo que clientes existentes continuem funcionando enquanto novos recursos são entregues. Sem isso, cada mudança vira um risco de interrupção.

1. Defina uma estrategia de versionamento antes do primeiro release

Comece pela decisão: URL, header ou query parameter. Cada uma tem trade-offs. URL é simples e explicita, mas polui o contrato. Header mantém a URL limpa, porém esconde a versão. O importante é escolher uma regra e aplicá-la consistemente.

Criterio: documente a escolha no guia de desenvolvimento. Se uma equipe nova entrar, ela segue o mesmo padrão.

2. Use versionamento semantico (SemVer)

SemVer define MAJOR.MINOR.PATCH. MAJOR para mudanças incompatíveis, MINOR para retrocompatíveis, PATCH para correções. Isso dá previsibilidade: clientes sabem o que esperar de cada release.

Exemplo: v2.1.0 indica nova funcionalidade sem quebrar contratos. v3.0.0 sinaliza quebra. Sem essa convenção, cada release vira uma caixa preta.

3. Nunca quebre contrato sem aviso prévio

Mudanças incompatíveis exigem um período de transição. O tempo varia, mas um minimo de 6 meses é comum. Durante esse periodo, mantenha a versão antiga ativa e informe claramente a data de descontinuação.

Ressalva: em APIs internas, o periodo pode ser menor. Mas mesmo assim, comunique com antecedencia.

4. Mantenha versões antigas por um periodo definido

Não desligue a versão anterior no dia seguinte. Defina uma politica de suporte, por exemplo, 12 meses após o lançamento da nova versão. Isso da tempo para clientes migrarem.

Criterio mensuravel: acompanhe o uso de cada versão. Quando o trafego da antiga cair abaixo de 5%, avalie a descontinuação.

5. Documente cada mudança de forma clara

Um changelog não é opcional. Liste o que mudou, o que foi adicionado e o que foi removido. Inclua exemplos de antes e depois. Isso reduz chamados de suporte e ajuda times a planejar migração.

Dica: use datas e numeros de versão no changelog. Facilita rastrear quando algo foi alterado.

6. Comunique depreciações com antecedencia

Depreciação é o aviso de que um recurso será removido. Envie notificações por email, no portal do desenvolvedor e no header da resposta (Deprecation). Isso permite que clientes se ajustem antes da remoção.

Contraexemplo: avisar apenas no changelog raramente funciona. Muitos clientes não leem.

7. Use headers de depreciação e sunset

Os headers Deprecation e Sunset indicam que um endpoint está obsoleto e quando será removido. Isso é padronizado e legível por maquinas, permitindo automatizar avisos.

Exemplo: Deprecation: true e Sunset: Wed, 31 Dec 2025 23:59:59 GMT. Simples e eficaz.

8. Teste compatibilidade com versões anteriores

Crie testes automatizados que rodem cenarios contra a versão antiga e a nova. Isso garante que você não quebrou algo sem perceber. Inclua testes de contrato, como os feitos com ferramentas de contract testing.

Dado: um teste de compatibilidade pode evitar horas de retrabalho. O custo de rodar é baixo, o custo de quebrar produção é alto.

9. Evite mudanças de formato de dados sem necessidade

Alterar de XML para JSON, ou mudar tipos de campo, é quebra garantida. Se precisar mudar, crie um novo endpoint ou uma nova versão. Não altere o formato no mesmo contrato.

Ressalva especifica: adicionar campos opcionais não quebra, mas remover ou renomear sim.

10. Forneça um endpoint de versão atual

Um endpoint GET /version ou GET /api/version informa qual versão está ativa. Isso ajuda clientes a diagnosticar problemas e a confirmar se estão na versão certa.

Exemplo de resposta: {"version": "2.1.0", "deprecated": false}. Simples de implementar, grande valor operacional.

11. Mantenha um sandbox com versões antigas

Permita que clientes testem contra versões antigas em um ambiente sandbox. Isso facilita a migração e reduz o risco de quebra em produção.

Criterio: o sandbox deve espelhar exatamente o comportamento da versão real, incluindo erros e limites.

12. Monitore o uso de cada versão

Acompanhe metricas de trafego por versão. Isso mostra quais clientes ainda usam versões antigas e quando é seguro descontinuar. Sem monitoramento, você decide no escuro.

Dado concreto: se 80% do trafego está na v3, a v2 pode ser descontinuada em breve, mas apenas se a politica de suporte permitir.

13. Automatize a geracao de documentacao por versão

Documentação gerada automaticamente a partir do codigo, como OpenAPI/Swagger, reduz erro humano. Cada versão tem sua propria spec, e a doc reflete exatamente o que está no ar.

Ressalva: automatizar não elimina a revisão humana. Alguem precisa validar se a doc está clara e completa.

Qual estrategia escolher?

Para APIs publicas, use versionamento na URL (v1, v2) combinado com SemVer e periodo de suporte longo. Para APIs internas, header ou query pode bastar, com ciclo mais curto. O essencial é ter uma politica explicita, documentada e comunicada. Comece pela simplicidade: defina a regra, registre no changelog e monitore o uso. O resto é consequencia.

FAQ

Quando devo criar uma nova versão da API?

Crie uma nova versão quando houver mudança incompatível, como remover campos, alterar tipos ou mudar regras de negocio. Mudanças retrocompatíveis, como adicionar campos opcionais, podem ser feitas na mesma versão.

Qual a diferenca entre versionamento por URL e por header?

URL deixa a versão visivel e simples de testar, mas polui o contrato. Header mantém a URL limpa, mas esconde a versão e exige mais configuracao. A escolha depende do perfil dos seus consumidores.

Como comunicar uma mudanca que quebra compatibilidade?

Use changelog, notificacoes no portal, headers Deprecation e Sunset, e um periodo de transicao. Avise com antecedencia, idealmente 6 a 12 meses, e ofereça suporte durante a migracao.

Posso mudar o formato de dados sem criar nova versão?

Não, se a mudanca for incompatível. Alterar o formato quebra contratos. Adicionar campos novos é seguro, mas remover ou renomear exige nova versão.

O que é SemVer e por que usar?

SemVer é um padrao de versionamento com MAJOR.MINOR.PATCH. MAJOR para quebras, MINOR para recursos retrocompatíveis, PATCH para correções. Ele dá previsibilidade e padroniza a comunicacao entre times.

Como saber quando descontinuar uma versão antiga?

Monitore o trafego por versão e defina uma politica de suporte. Quando o uso da versão antiga cair abaixo de um limite, como 5%, e o periodo de aviso terminar, descontinue.