Quando a API está em desenvolvimento, é importante manter a compatibilidade entre as versões e evitar que uma única mudança rompa dezenas de integrações de clientes. Implementamos uma versão completa dos contratos que permite controlar as alterações e atualizar a API de forma suave, sem risco para os usuários.
Isso é crucial na arquitetura de microsserviço, integração B2B e produtos API abertos, onde diferentes clientes usam diferentes versões de interfaces.
O que estamos a versionizar
| Objeto | Descrição |
|---|---|
| OpenAPI especificações | Armazenando cada versão da documentação e do contrato |
| Endpoint'ы | Adicionando versões ao URL ('/v1/', '/v2/'), salvando backward compatibilidade |
| Contratos (Pact, Dredd) | Fixar condições de interação entre o cliente e o servidor |
| Modelos de dados | Controlar alterações na estrutura de consulta e resposta |
Como implementamos
Suporte a várias APIs paralelas
Especificação explícita de versão em URL, cabeçalhos ou parâmetros
Autodeclaração de cada versão dos contratos (Pact, Postman, Jest, Dredd)
Versionização de especificações em Git ou via CI/CD
Documentação e changelog para clientes a cada mudança
Vantagens
Estabilidade garantida das integrações
Capacidade de produzir novos fichas sem risco de «quebrar» clientes
Simplificar migração entre versões
Histórico claro de mudanças e controle de contratos
Transparência para comandos de desenvolvimento externos e internos
Onde é particularmente importante
Arquitetura de microsserviço com múltiplas dependências
Plataformas com API pública ou B2B
Sistemas financeiros e de pagamentos com contratos de longo prazo
Aplicativos móveis dependentes de API estável
A versionização dos contratos é uma base de previsibilidade e confiança na API. Introduzimos processos que permitem alterar e desenvolver API sem dor, mantendo compatibilidade e transparência para todas as partes.