O que é Versionamento de API
Gerenciamento de versões de API
Versionamento de API
Versionamento de API é a prática de gerenciar mudanças na API mantendo compatibilidade retroativa para clientes existentes.
Estratégias de versionamento
| Estratégia | Exemplo | Descrição | |------------|---------|-----------| | Caminho URL | /api/v1/users | Versão no caminho URL | | Parâmetro Query | /api/users?version=1 | Versão no parâmetro | | Header | X-API-Version: 1 | Versão no cabeçalho | | Content Type | Accept: application/vnd.api.v1+json | Versão do media type |
Versionamento semântico
- Major (v1→v2) — mudanças incompatíveis
- Minor (v1.1→v1.2) — novas funcionalidades, compatível
- Patch (v1.1.0→v1.1.1) — correções de bugs
Melhores práticas
- Documentar todas as mudanças (changelog)
- Suportar pelo menos 2 versões
- Anunciar deprecação com antecedência
- Usar headers sunset
- Fornecer ferramentas de migração
Quando uma nova versão é necessária
- Remoção de campos ou endpoints
- Mudança no formato de resposta
- Mudança na semântica dos parâmetros
- Mudança na autenticação