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 pagamento 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.
Temas populares
Temas principais
Contactar-nos
Preencha o formulário abaixo e responderemos o mais rapidamente possível.