Versionamento API: 10 boas práticas para aplicar já

Versionar uma API é a prática de gerenciar de modo transparente as alterações em sua interface. O objetivo é simples: permitir que o serviço evolua sem quebrar quem já usa. Sem uma estratégia, uma mudança simples pode derrubar integrações inteiras. As 10 boas práticas abaixo ajudam a evitar esse cenário, do planejamento à descontinuação.

1. Defina uma política de versionamento antes do primeiro deploy

A política precisa existir antes de a API ganhar o primeiro consumidor. Sem ela, cada mudança vira um debate sobre onde colocar a versão, quando incrementar e como comunicar. Uma política escrita, mesmo que curta, define regras para todos.

Um critério concreto: determine que mudanças que quebram compatibilidade exigem versão nova, enquanto adições opcionais não. Isso evita que cada campo novo na resposta vire uma versão inteira.

2. Escolha o método de versionamento adequado ao seu caso

Existem três formas comuns: URI (v1, v2), query parameter (?v=1) e header (Accept: application/vnd.api+json;version=1). Cada uma tem trade-offs. URI é visível e simples de debugar, mas polui a URL. Header mantém a URL limpa, porém esconde a versão. Query parameter é fácil de testar, mas pode ser cacheado por engano.

Um exemplo prático: APIs públicas costumam usar URI pela transparência. APIs internas, com clientes controlados, podem preferir header. A escolha depende do seu contexto, não de moda.

3. Versionamento por URI é o mais comum, mas não ignore o header

O versionamento por URI, como /v1/clientes, é o padrão de mercado. Ele aparece na documentação, nos logs e nas ferramentas de debugging. Para a maioria dos times, é o ponto de partida mais simples.

Contudo, quando a API evolui com frequência, o header de versão reduz o acoplamento. Um estudo interno da Sensedia aponta que a escolha do método impacta diretamente a manutenção a longo prazo. Avalie o perfil dos seus consumidores antes de decidir.

4. Nunca quebre contrato sem aviso prévio

Uma mudança que remove campo, altera tipo ou muda status code é quebra de contrato. Ela exige aviso, não surpresa. Documente a mudança, comunique por canal oficial e dê prazo para migração.

Um prazo razoável varia de semanas a meses. APIs críticas, usadas por terceiros, precisam de mais tempo. O aviso prévio não é cortesia, é prevenção de incidente.

5. Mantenha versões antigas por um período definido

Descontinuar uma versão da noite para o dia gera instabilidade. Defina um ciclo de vida: versão atual, versão em depreciação e versão removida. Durante a depreciação, a API continua funcionando, mas retorna um header de aviso, como Deprecation: true.

Um número concreto: muitas empresas mantêm versões antigas por 12 a 18 meses. O período precisa ser documentado e cumprido, para que o consumidor confie no processo.

6. Documente cada versão separadamente

Documentação única para várias versões confunde. Cada versão precisa de sua própria referência, com endpoints, exemplos e diferenças em relação à anterior. Isso reduz chamados de suporte e acelera a integração.

Uma boa prática associada: inclua um changelog por versão, listando o que mudou, o que foi adicionado e o que foi removido. O changelog é a ponte entre a equipe de API e o consumidor.

7. Automatize testes de compatibilidade

Testes manuais para verificar se uma versão nova quebrou a anterior são lentos e falhos. Automatize testes de contrato, que validam se a resposta bate com o schema esperado. Ferramentas como Postman, Pact ou Dredd ajudam nessa tarefa.

Um critério mensurável: rode os testes de compatibilidade a cada deploy. Se uma mudança quebrar a versão anterior, o pipeline falha antes de chegar à produção.

8. Use depreciação com headers e avisos claros

Headers de depreciação, como Deprecation e Sunset, informam o consumidor sobre o ciclo de vida da versão. O header Sunset indica a data de remoção. Isso automatiza o aviso, sem depender de e-mail ou chat.

Um exemplo: ao chamar /v1/clientes, a resposta pode incluir Deprecation: true e Sunset: Wed, 31 Dec 2025 23:59:59 GMT. O cliente sabe, pelo código, que precisa migrar.

9. Versionamento semântico ajuda, mas não é obrigatório

O versionamento semântico (MAJOR.MINOR.PATCH) é útil para APIs, mas não resolve tudo. Ele indica o tipo de mudança, não o método de versionamento. Uma versão MAJOR nova pode coexistir com a anterior, enquanto MINOR e PATCH não exigem versão separada.

Um cuidado: não confunda versão do artefato com versão da API. A API pode ter /v1, enquanto o código interno usa 2.3.1. O consumidor precisa da versão da API, não da implementação.

10. Monitore o uso de cada versão

Sem métricas, você não sabe quem usa a versão antiga nem quando pode descontinuá-la. Monitore chamadas por versão, endpoints mais usados e erros por versão. Esses dados orientam a decisão de desligar uma versão.

Um número prático: quando o tráfego de uma versão antiga cai abaixo de 1% do total, é seguro planejar a remoção. O monitoramento transforma a descontinuação em processo, não em palpite.

Como escolher a estratégia certa

A melhor estratégia depende do seu contexto. APIs públicas, com muitos consumidores externos, favorecem URI e prazos longos. APIs internas, com times enxutos, podem usar header e ciclos mais curtos. O essencial é documentar a escolha, comunicar mudanças e automatizar testes. Comece com o básico: política escrita, método definido e monitoramento ativo.

Perguntas frequentes sobre versionamento de API

O que é versionamento de API?

É o processo de gerenciar mudanças na estrutura de uma API, garantindo que versões antigas continuem funcionando enquanto novas são lançadas. Envolve definir regras para alterações, comunicação e descontinuação.

Qual é a melhor forma de versionar uma API?

Não existe uma única. URI é a mais comum e transparente. Header é mais limpa, mas esconde a versão. Query parameter é simples, porém arriscado com cache. A escolha depende do público e da frequência de mudanças.

O que é quebra de contrato em uma API?

É qualquer mudança que torne a resposta ou o comportamento incompatível com o que os clientes esperam. Exemplos: remover um campo, mudar o tipo de dado ou alterar um código de status sem aviso.

Por que manter versões antigas de API?

Para dar tempo de os consumidores migrarem sem interrupção. Descontinuar de forma abrupta pode causar falhas em sistemas críticos. Um período de depreciação, com avisos claros, reduz riscos.

Como comunicar mudanças em uma API?

Use documentação, changelog, e-mails e headers de depreciação. O header Sunset informa a data de remoção automaticamente. A comunicação precisa ser clara, antecipada e registrada em canal oficial.

O que é versionamento semântico em APIs?

É um sistema de numeração (MAJOR.MINOR.PATCH) que indica o tipo de mudança. MAJOR quebra compatibilidade, MINOR adiciona funcionalidade e PATCH corrige bugs. Ele ajuda a comunicar impacto, mas não substitui a estratégia de versionamento.