Versionamento de API: Guia de Evolução Sem Quebra

APIs evoluem. Features novas, correções, deprecações. Mas clientes dependem da interface atual. Versionamento permite evolução sem quebrar aplicativos existentes. Este guia apresenta estratégias e boas práticas.

Por Que Versionar

Compatibilidade

Clientes antigos continuam funcionando.

Evolução

Melhorar sem bloquear.

Documentação

Clareza sobre o que esperar.

Transição

Tempo para clientes migrarem.

Quando Versionar

Breaking Changes

Mudanças que quebram contratos.

Exemplos

Remover campo
Mudar tipo de dado
Alterar significado
Remover endpoint

Não Versionar Para

Adições, que são geralmente compatíveis.

Estratégias de Versionamento

URL Path

/api/v1/users, /api/v2/users.

Query Parameter

/api/users?version=1.

Header

Accept-Version: v1 ou API-Version: 2.

Content Negotiation

Accept: application/vnd.myapi.v1+json.

URL Path Versioning

Vantagens

Visível, claro, fácil de rotear.

Desvantagens

URLs mudam com versão.

Exemplo

GET /api/v1/products GET /api/v2/products

Comum

Abordagem mais popular.

Header Versioning

Vantagens

URLs limpas, semanticamente correto.

Desvantagens

Menos visível, mais difícil de testar.

Exemplo

GET /api/products Header: API-Version: 2

Semantic Versioning

Formato

MAJOR.MINOR.PATCH.

MAJOR

Breaking changes.

MINOR

Adições compatíveis.

PATCH

Bug fixes.

Para APIs

Geralmente só MAJOR na versão pública.

Deprecation

Processo

Marcar como deprecated antes de remover.

Comunicação

Headers, documentação, changelog.

Timeline

Prazo para migração.

Suporte

Quanto tempo manter deprecated.

Sunset Headers

HTTPHeader

Sunset: Sat, 01 Jul 2024 00:00:00 GMT.

Deprecation Header

Indica que está deprecated.

Comunicação

Clientes podem detectar automaticamente.

Migração

Documentação

O que mudou, como adaptar.

Guias

Passo a passo de migração.

Suporte

Ajuda durante transição.

Timeline

Prazo razoável.

Compatibilidade Backward

Objetivo

Novos clientes, antigas APIs funcionam.

Aditivo

Adicione, não remova.

Default Values

Novos campos com defaults.

Optional

Novos parâmetros opcionais.

Compatibilidade Forward

Conceito

Clientes antigos com APIs novas.

Ignore Unknown

Ignore campos desconhecidos.

Graceful Degradation

Funcione sem novos features.

Design para Evolução

Extensibilidade

Pense em mudanças futuras.

Generic Structures

Objetos extensíveis.

Feature Flags

Não exponha features incompletas.

Contratos

Defina claramente o que promete.

Multiplas Versões

Manutenção

Custo de manter várias.

Limites

Quantas suportar simultaneamente.

Política

Defina regras claras.

Documentação

Por Versão

Docs específicos por versão.

Changelog

O que mudou entre versões.

Migration Guides

Como atualizar.

Deprecation Notices

O que vai sair.

Ferramentas

OpenAPI/Swagger

Especificação versionada.

Postman

Collections por versão.

API Gateways

Roteamento por versão.

Erros Comuns

Versionar Demais

Nova versão para cada mudança.

Não Versionar

Breaking change sem versão nova.

Deprecar Rápido

Não dar tempo para migração.

Sem Comunicação

Clientes surpresos com mudanças.

SDKs e Clientes

Versões Correspondentes

SDK v1 para API v1.

Manutenção

Manter SDKs atualizados.

Comunicação

Notificar sobre novas versões.

Conclusão

Versionamento de API é disciplina de longo prazo. Escolha estratégia clara, comunique mudanças e dê tempo para migração. O resultado são APIs que evoluem sem quebrar integrações.

FAQs

1) Qual estratégia de versionamento usar? URL path é mais comum e recomendado para maioria.

2) Quando incrementar versão major? Para breaking changes que não são backward compatible.

3) Quanto tempo suportar versão antiga? 6-12 meses é comum. Depende de clientes.

4) Posso fazer mudanças sem versionar? Adições geralmente sim. Remoções/alterações não.

5) Como comunicar deprecation? Headers, docs, emails, período de transição.