Blog

Versionamento de API: como avaliar a política de breaking changes de um fornecedor

UNIFOKAL7 min de leituraProduto e integração

Aprenda a separar breaking change real de evolução compatível e a avaliar changelog, prazo de depreciação, header Sunset e sandbox antes de fechar com um fornecedor de KYC.

Toda integração com um fornecedor de verificação de identidade nasce com uma promessa implícita: o que funciona hoje continua funcionando amanhã. Quando essa promessa falha sem aviso, o problema aparece no pior lugar possível. O onboarding de clientes para, a esteira de análise trava, e a causa costuma ser pequena: um campo que sumiu da resposta, um formato de data que mudou, uma validação que ficou mais rígida do lado de lá.

Quem está escolhendo um fornecedor de KYC (Know Your Customer, o processo de conhecer o cliente) tende a comparar preço, cobertura de dados e qualidade de detecção. A política de versionamento da API (Application Programming Interface, a interface de integração do serviço) raramente entra na planilha, e é justamente ela que determina o custo da integração depois de pronta. Um fornecedor que muda o contrato sem cerimônia transforma cada evolução do produto dele em um incidente no seu.

A boa notícia é que essa maturidade dá para avaliar de fora, antes de assinar. Este texto mostra o que é uma quebra de contrato de verdade, quais sinais públicos separam fornecedores cuidadosos de caóticos, o que perguntar na diligência e como se proteger seja qual for a resposta.

O que é breaking change de verdade (e o que não é)

Breaking change é qualquer mudança que obriga quem consome a API a alterar código para continuar funcionando. Quatro categorias concentram quase todos os casos:

  • Remover ou renomear um campo da resposta. O código que lia "status" não descobre sozinho que agora o nome é "decision_status".
  • Mudar o tipo ou o formato de um campo: um valor que era texto vira número, uma data em DD/MM/AAAA vira AAAA-MM-DD. O parse quebra ou, pior, passa a interpretar errado em silêncio.
  • Mudar a semântica de um valor sem mudar a forma: mesmo campo, mesmo tipo, significado novo. Se "pending" passa a englobar casos que antes eram "failed", nenhuma validação de formato acusa, mas a sua régua de decisão fica errada.
  • Apertar a validação de entrada: uma requisição aceita ontem passa a ser rejeitada hoje, porque um campo virou obrigatório ou um limite diminuiu.

A referência para o comportamento observável de uma API na web é a RFC 9110 (RFC, Request for Comments, é a série de documentos técnicos que padroniza a internet), que define a semântica do HTTP (Hypertext Transfer Protocol): métodos, códigos de status e cabeçalhos. Quando um endpoint que respondia 200 passa a responder 400 para a mesma requisição, o contrato mudou, diga o que disser a documentação.

Igualmente importante é o que não é breaking change:

  • Campo novo na resposta. Adicionar informação não remove nada do que você já usava.
  • Valor novo em um enum documentado como aberto. Se a documentação avisa que a lista de motivos de reprovação pode crescer, um motivo inédito é evolução prevista, não quebra.
  • Ordem dos campos no objeto JSON (JavaScript Object Notation). A RFC 8259, que especifica o formato, define objeto como coleção de pares nome e valor sem ordem significativa. Código que depende da posição de um campo já nasceu quebrado.

Fornecedor maduro escreve essa distinção na própria documentação: o que ele se reserva o direito de mudar sem aviso e o que promete nunca mudar dentro de uma versão.

A sua metade do contrato: o leitor tolerante

A distinção acima só funciona se o integrador fizer a parte dele. O padrão é conhecido como leitor tolerante: o cliente da API lê apenas os campos que usa, ignora o que não conhece e não falha quando aparece algo a mais na resposta.

Na prática, são três hábitos:

  1. Não validar a resposta inteira contra um esquema fechado que rejeita campos desconhecidos. Valide os campos dos quais o seu fluxo depende.
  2. Tratar todo enum documentado como aberto com um caminho padrão. Um status inédito deve cair em comportamento seguro, como revisão manual, nunca em exceção não tratada.
  3. Nunca depender de ordem de campos nem de detalhes de serialização.

A tolerância tem limite claro: ela cobre mudança aditiva. Ela não desobriga o fornecedor de avisar sobre remoções e mudanças de semântica, e não substitui monitoramento. Leitor tolerante é proteção contra ruído, não contra quebra.

Semantic Versioning dá o vocabulário, mas não resolve API HTTP

A Semantic Versioning 2.0.0 (SemVer), especificação publicada em semver.org, define o formato maior.menor.correção: incrementa-se a versão maior em mudança incompatível, a menor em funcionalidade nova compatível e a correção em conserto de defeito compatível. Esse vocabulário é útil na diligência porque dá nome preciso às coisas: quando o fornecedor diz que uma mudança "é só uma minor", está afirmando compatibilidade com o que existe.

O limite é que a SemVer foi pensada para software distribuído como pacote, com o número completo declarado em dependência. Uma API HTTP não é consumida assim: a versão costuma viver no caminho da URL (Uniform Resource Locator), como /v1, ou em um cabeçalho de requisição, e quase sempre só a versão maior aparece. As mudanças menores e as correções acontecem em silêncio debaixo do mesmo v1.

Por isso, "seguimos SemVer" é resposta incompleta. As perguntas que importam: o que exatamente o fornecedor classifica como mudança maior, onde essa versão aparece na chamada, e o que acontece com as versões anteriores quando uma nova é publicada.

Sinais públicos de um fornecedor maduro

Antes de qualquer reunião comercial, a documentação pública já responde muita coisa. Procure por:

  • Changelog público e datado. Cada mudança registrada, com data e classificação de impacto. Changelog é o histórico comportamental do fornecedor: se não existe, o histórico é inacessível por definição. Na UNIFOKAL, por exemplo, a documentação pública mantém changelog aberto justamente por isso.
  • Política de depreciação escrita, com prazo mínimo entre anúncio e desligamento. Mais importante que o número é a evidência de cumprimento: anúncios antigos ainda visíveis, com as datas prometidas e as datas reais.
  • Aviso de desligamento legível por máquina. A RFC 8594 define o cabeçalho HTTP Sunset, que informa na própria resposta a data a partir da qual o recurso deixará de estar disponível. Um fornecedor que envia Sunset, ou um aviso equivalente e documentado, permite que o seu sistema alerte sozinho sobre depreciação, sem depender de alguém ler e-mail.
  • Versões antigas com data de fim clara. "Suportamos v1 indefinidamente" costuma significar "não temos plano". Data explícita significa ciclo de vida gerenciado.
  • Sandbox com a versão nova disponível antes do desligamento da antiga, para ensaiar a migração sem tocar produção.

Esses sinais valem para qualquer serviço crítico e complementam os critérios gerais de avaliação de um fornecedor de KYC.

Perguntas de diligência e as defesas que só dependem de você

Na conversa com o fornecedor, três perguntas objetivas revelam mais que qualquer slide institucional:

  1. Qual foi o último breaking change e como foi comunicado? Peça o anúncio real: a data, o canal, o prazo dado. Resposta vaga aqui já é o dado.
  2. Qual é o prazo mínimo garantido entre anúncio e desligamento? E se está em contrato ou apenas numa página que pode mudar.
  3. O que acontece com quem não migra no prazo? Erro explícito com mensagem clara é aceitável; comportamento silenciosamente diferente é o pior cenário.

E, independentemente das respostas, três defesas ficam do seu lado da fronteira:

  • Teste de contrato no CI (integração contínua) rodando contra a resposta real do sandbox, não contra mocks. Mock só prova que o seu código concorda com a sua memória do contrato; é o teste contra o serviço vivo que pega o drift antes do deploy.
  • Monitoramento dos campos que o seu código realmente usa em produção: alarme quando um campo esperado desaparece, muda de tipo ou passa a vir vazio. Isso encurta o tempo entre quebra e detecção, e é parte do monitoramento contínuo da integração.
  • Plano de migração ensaiado. Se a troca de versão, ou de fornecedor, nunca foi exercitada, o prazo de depreciação vira corrida. Quem já mapeou os pontos de acoplamento, como descrito em migrar de fornecedor de KYC, trata depreciação como rotina, não como crise.

No fim, a política de breaking changes é um teste de caráter técnico: mostra como o fornecedor trata o tempo e o código de quem depende dele. Quem documenta, avisa com prazo, cumpre o prazo e oferece onde testar merece a sua integração. O resto merece, no máximo, uma segunda cotação.

Fontes citadas