Versionização de contratos

Versionização de contratos

Quando a API está em desenvolvimento, é importante manter a interconexão entre as versões e evitar situações em que uma única mudança rompe dezenas de integrações de clientes. Nós implementamos uma versionização completa de 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	Armazenamos cada versão da documentação e contrato
Endpoint's	Adicionando versões ao URL ('/v1/', '/v2/'), salvando backward compatibilidade
Contratos (Pact, Dredd)	Fixar termos de interação entre cliente e 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.