O que é API Versioning
API Versioning (versionamento de API) é a prática de manter e gerenciar múltiplas versões de uma API simultaneamente, permitindo que a equipe de desenvolvimento evolua a interface (adicione campos, mude formatos, remova endpoints) sem quebrar aplicações clientes que ainda usam versões anteriores.
Sem versionamento adequado, qualquer mudança breaking (que altera comportamento existente) pode derrubar integrações de parceiros, apps mobile já publicados na loja e clientes que não conseguem atualizar imediatamente. Empresas como Stripe e GitHub mantêm versões antigas ativas por anos para garantir estabilidade dos integradores.
Estratégias de versionamento
- URI Path: /v1/users — mais comum e visível (GitHub, Twitter)
- Query String: /users?version=1 — simples mas menos elegante
- HTTP Header: Accept-Version: v1 — limpo mas menos descobrível
- Content Negotiation: Accept: application/vnd.api.v1+json — padrão HTTP
- Date-based: Stripe-Version: 2024-06-20 — flexível para evoluções contínuas (Stripe)
Breaking vs Non-Breaking Changes
Mudanças não-breaking (adicionar campo opcional, novo endpoint) não exigem nova versão. Mudanças breaking (remover campo, mudar tipo, alterar comportamento) devem disparar nova versão. Seguir Semantic Versioning (MAJOR.MINOR.PATCH) ajuda a comunicar a natureza de cada mudança.
Boas práticas
Documente políticas de deprecação claras (ex: versões antigas suportadas por 12 meses), use cabeçalhos como Deprecation e Sunset, e ofereça migração assistida. Combinar com API Gateway facilita o roteamento entre versões.
Leia o artigo completo: API Versioning: estratégias para evoluir APIs sem quebrar clientes
