Contrato de API e versionamento em integração crítica
Um serviço de pagamentos de boletos expõe uma API REST consumida por três parceiros e por dois sistemas internos. O contrato atual (v1) retorna o campo status como texto livre com valores como 'PAGO', 'pago', 'LIQUIDADO' e 'em processamento'. Um novo requisito exige padronizar status em um enum fechado e adicionar o campo data_liquidacao em formato ISO 8601. A equipe propõe simplesmente alterar a v1, argumentando que 'todos vão se adaptar'. Um dos parceiros processa 300 mil boletos por dia e só pode fazer deploy a cada 45 dias. Outro parceiro não tem contrato de manutenção ativo e não responde há duas semanas. O banco de dados armazena os status em uma coluna VARCHAR sem constraint, com registros históricos em cinco grafias diferentes.
1. A alteração direta na v1 é adequada? Justifique com base em compatibilidade e risco operacional.
Read the worked answer
Não é adequada. Alterar o contrato em uso quebra compatibilidade: clientes que comparam status com strings antigas passariam a falhar silenciosamente ou a rejeitar respostas, gerando boletos não conciliados. O parceiro de 300 mil boletos por dia tem janela de deploy de 45 dias, incompatível com uma mudança imediata; o parceiro sem contrato ativo sequer pode ser notificado, o que configura risco não mapeado.
A prática correta é versionar: publicar v2 com o enum e o novo campo, manter v1 funcionando durante um período de convivência com prazo comunicado, e registrar formalmente a depreciação. Para o parceiro sem contato, é preciso escalar pelo canal comercial e considerar prazo estendido ou bloqueio de novas adesões à v1. Mudanças aditivas (novo campo opcional) são compatíveis; mudanças de tipo ou de domínio de valor não são.
2. Descreva a estratégia de migração de dados e de contrato, incluindo como lidar com as cinco grafias históricas.
Read the worked answer
Primeiro, mapear as cinco grafias para o enum canônico e criar uma tabela de correspondência explícita, tratando casos ambíguos manualmente. Em seguida, adicionar uma coluna nova tipada (ou constraint CHECK) sem remover a antiga, preencher por backfill em lotes e manter a aplicação gravando nos dois formatos durante a transição.
Na API, a v2 expõe o enum e data_liquidacao em ISO 8601; a v1 continua respondendo no formato antigo, com uma camada de tradução. Publicar changelog, exemplos e ambiente de testes, além de monitorar erros por cliente. Só após o prazo de convivência e com evidência de que nenhum consumidor usa a v1, desativá-la e, por fim, remover a coluna legada. O risco a controlar é o backfill concorrer com escritas; usar lotes, idempotência e janela de baixo tráfego, com rollback planejado.