Contrato de API sem versão: evoluir o payload sem quebrar o cliente antigo

A primeira reação de quase todo time diante desse problema é criar um prefixo de versão e prometer que a partir de agora toda mudança entra em uma versão nova. A promessa dura até a terceira mudança. Manter duas versões completas de uma API significa manter dois caminhos de código, dois conjuntos de testes, duas rotinas de correção de bug e duas superfícies de segurança, e o custo disso é alto o suficiente para que a segunda versão sempre acabe sendo um repasse fino para a mesma implementação da primeira. No momento em que isso acontece, a versão na URL virou decoração: a mudança de comportamento vaza para os dois lados porque só existe um lado de verdade.

O contrato de uma API não é a rota, é o conjunto de suposições que o cliente faz sobre o que ele recebe e o que ele pode mandar. Um cliente que lê o campo de total supõe que ele existe, que é um número, que está em centavos, que não é nulo em pedido concluído, e que o valor cabe no tipo usado para desserializar. Nenhuma dessas suposições aparece na URL, e qualquer uma delas pode ser violada sem trocar de versão. A pergunta útil não é qual versão o cliente chama, é quais dessas quatro suposições a sua mudança está prestes a violar.

As duas linhas que costumam surpreender são a do enumerado e a do relaxamento de validação. Adicionar o status de entrega parcial a um campo que antes só tinha três valores parece a mudança mais inofensiva possível, e derruba todo cliente escrito em linguagem com tipos fechados ou com um desvio condicional sem ramo padrão. Relaxar a validação de um campo de texto de cinquenta para quinhentos caracteres não quebra ninguém na entrada, e quebra o cliente que reserva cinquenta caracteres no banco dele no dia em que alguém usar os quinhentos. As duas têm a mesma assinatura: a mudança é aditiva do lado do servidor e restritiva do lado de quem consome.

A intuição de que adicionar é seguro e remover é perigoso está certa em média e errada nos casos que causam incidente. Adicionar um campo é seguro quando o cliente ignora o que não conhece, e essa é a configuração padrão da maioria das bibliotecas de desserialização. Mas basta um cliente ter ligado a validação estrita de esquema, ou usar uma biblioteca que falha diante de propriedade desconhecida por padrão, ou validar a resposta contra um esquema gerado a partir da especificação de dois anos atrás, para que a adição vire erro. O detalhe cruel é que esse erro acontece no cliente, aparece no log do cliente, e não gera nenhum sinal do lado do servidor: a sua taxa de erro continua em zero enquanto a integração do parceiro está caída.

// contract/compat.js
// A mesma resposta enviada para tres clientes com politicas de
// desserializacao diferentes. Adicionar um campo e seguro em um caso e
// fatal nos outros dois, e o servidor nao consegue distinguir.

const resposta = {
  id: 'ped_8812',
  total: 24990,          // centavos
  moeda: 'BRL',
  status: 'pago',
  descontoAplicado: 500, // campo novo, adicionado hoje
};

// Cliente A: ignora o que nao conhece. Continua funcionando.
const clienteTolerante = (json) => ({
  id: json.id,
  total: json.total,
});

// Cliente B: valida esquema fechado. Passa a rejeitar a resposta inteira
// por causa de um campo que ele nem queria ler.
const esquemaFechado = new Set(['id', 'total', 'moeda', 'status']);

const clienteEstrito = (json) => {
  for (const chave of Object.keys(json)) {
    if (!esquemaFechado.has(chave)) {
      throw new Error('propriedade desconhecida: ' + chave);
    }
  }
  return { id: json.id, total: json.total };
};

// Cliente C: mapeia o enumerado para um conjunto fechado. Sobrevive ao
// campo novo e morre no dia em que um status novo for adicionado.
const clienteEnumerado = (json) => {
  switch (json.status) {
    case 'pendente':
      return { pagavel: true };
    case 'pago':
      return { pagavel: false };
    case 'cancelado':
      return { pagavel: false };
    default:
      throw new Error('status desconhecido: ' + json.status);
  }
};

// A unica mudanca que os tres toleram e a que nao altera o conjunto de
// chaves nem o dominio de valores dos campos existentes. Qualquer outra
// precisa ser medida antes, nao anunciada depois.
export { clienteTolerante, clienteEstrito, clienteEnumerado, resposta };

A conclusão prática é que a compatibilidade não é uma propriedade da mudança, é uma propriedade do par formado pela mudança e pelo comportamento real dos clientes que existem hoje. Você não sabe qual dos três clientes acima está do outro lado, e não vai descobrir perguntando, porque quem responde a um formulário de integração é quem lembra de responder, não quem tem o código mais antigo em produção. A única fonte confiável é o tráfego, e é por isso que a primeira etapa de qualquer evolução de contrato é instrumentar antes de mudar.

Do lado da requisição a medição é direta: cada campo que chega é observável, e registrar quais chaves o cliente enviou já responde quem depende do quê. Do lado da resposta o problema é mais difícil, porque o servidor manda tudo e não vê o que o cliente lê. Existem três formas práticas de recuperar essa informação, e a ordem de preferência é a mesma em quase todo sistema.

1. Pedir ao cliente que declare o que quer. Um parâmetro de seleção de campos, uma consulta com projeção explícita ou um cabeçalho de perfil de resposta transformam a leitura em algo declarado. É a única forma que dá certeza, e é a que exige mudança do outro lado, então serve para clientes novos e não resolve o legado.
2. Retirar o campo de uma fatia pequena do tráfego e observar quem reclama. É a forma mais barata de descobrir dependência real: remova o campo para um por cento das requisições de um cliente específico, mantenha por vinte e quatro horas e veja se a taxa de erro dele muda. Funciona bem quando você consegue segmentar por credencial e reverter em segundos.
3. Correlacionar por comportamento observável. Se o cliente lê o total e o campo passa a vir errado, ele para de criar cobranças, ou passa a criar cobranças com valor diferente, ou aumenta a taxa de nova tentativa. Nem sempre existe um sinal desses, mas quando existe ele é o mais honesto, porque mede consequência e não intenção.

// contract/uso-de-campo.js
// Instrumentacao minima para responder "quem ainda depende deste campo".
// Registra por credencial, nao por rota, porque a decisao de remover e
// sempre sobre um cliente concreto e nao sobre um endpoint.

const janelaMs = 30 * 24 * 60 * 60 * 1000; // 30 dias
const uso = new Map(); // chave: clienteId + '|' + campo -> ultimoUsoMs

const chaveDe = (clienteId, campo) => clienteId + '|' + campo;

export const registrarCamposRecebidos = (clienteId, corpo) => {
  const agora = Date.now();
  for (const campo of Object.keys(corpo || {})) {
    uso.set(chaveDe(clienteId, campo), agora);
  }
};

// Para a resposta o servidor nao observa a leitura. O que ele observa e a
// declaracao: quando o cliente pede projecao, isso e leitura confirmada.
export const registrarCamposSolicitados = (clienteId, campos) => {
  const agora = Date.now();
  for (const campo of campos) {
    uso.set(chaveDe(clienteId, campo), agora);
  }
};

// Relatorio que decide a remocao: quais clientes tocaram o campo dentro da
// janela. Lista vazia nao prova ausencia de uso, prova ausencia de
// evidencia, e a diferenca entre as duas coisas e o que separa uma
// remocao planejada de um incidente.
export const clientesQueUsam = (campo, agora = Date.now()) => {
  const limite = agora - janelaMs;
  const encontrados = [];
  for (const [chave, ultimoUso] of uso) {
    const separador = chave.lastIndexOf('|');
    const clienteId = chave.slice(0, separador);
    const campoRegistrado = chave.slice(separador + 1);
    if (campoRegistrado === campo && ultimoUso >= limite) {
      encontrados.push({ clienteId, ultimoUso });
    }
  }
  return encontrados.sort((a, b) => b.ultimoUso - a.ultimoUso);
};

// Cobertura da medicao: sem isso o relatorio acima e enganoso, porque um
// cliente que integra uma vez por trimestre nao aparece na janela.
export const coberturaDaJanela = (clienteId, agora = Date.now()) => {
  const limite = agora - janelaMs;
  const prefixo = clienteId + '|';
  for (const [chave, ultimoUso] of uso) {
    if (chave.startsWith(prefixo) && ultimoUso >= limite) {
      return { observado: true };
    }
  }
  return { observado: false, motivo: 'cliente silencioso na janela' };
};

A função de cobertura é a parte que costuma faltar e é a que evita o erro mais caro dessa etapa. Um relatório que diz que nenhum cliente usou o campo nos últimos trinta dias parece autorização para remover, e não é: pode significar que ninguém usa, ou que o cliente que usa integra uma vez por trimestre no fechamento contábil. A janela de observação precisa ser maior que o maior período de chamada dos seus clientes, e para integração financeira isso raramente é menos de treze meses.

O roteiro que resolve migração de esquema de banco sem janela de manutenção resolve evolução de contrato pelo mesmo motivo: em ambos existe um período em que dois formatos precisam coexistir e o escritor não controla o leitor. A diferença é que no banco o leitor é o seu próprio código e a contração leva semanas, enquanto na API o leitor é de outra empresa e a contração leva trimestres. A estrutura das quatro etapas é idêntica.

EXPANDIR  (semana 0)
  resposta: { valorTotal: 24990, total: 24990 }
  requisicao aceita: valorTotal OU total, ambos validos
  regra: se os dois vierem e divergirem, erro explicito 422
         (aceitar em silencio esconde o bug do cliente)

MIGRAR    (semana 0 ate a evidencia parar)
  clientes novos: documentacao mostra so valorTotal
  clientes antigos: cabecalho Deprecation + Sunset na resposta
  metrica por credencial: quem ainda toca 'total'

MEDIR     (janela >= maior periodo de chamada do cliente)
  relatorio semanal: clientes com uso de 'total' na janela
  contato individual, nao aviso em changelog
  criterio de saida: zero uso E cobertura confirmada

CONTRAIR  (so depois do criterio)
  remocao gradual: 1% -> 10% -> 50% -> 100% do trafego
  reversao em um comando ate os 100%
  campo removido da resposta e rejeitado na requisicao

O QUE NUNCA E ETAPA
  anunciar no changelog e remover no prazo anunciado
  sem medir uso: o prazo mede a sua paciencia, nao o risco

A regra do erro explícito quando os dois campos chegam divergentes é a parte contraintuitiva e a que evita o pior desfecho. A tentação é aceitar o campo novo e ignorar o antigo, porque isso mantém a requisição funcionando. O problema é que um cliente que manda os dois com valores diferentes tem um defeito, e aceitar em silêncio significa gravar o valor errado sem que ninguém descubra até a conciliação. Responder com erro de validação transforma um dado corrompido em um chamado de suporte, e chamado de suporte é infinitamente mais barato.

A remoção gradual por porcentagem de tráfego é o que diferencia contração de aposta. Remover para um por cento das requisições durante um dia e observar a taxa de erro por credencial expõe o cliente que a medição não pegou, e expõe com um por cento de dano em vez de cem. A regra de operação é que a reversão precisa ser um comando único e imediato até o momento em que o percentual chega a cem, porque é exatamente nessa faixa que o cliente silencioso aparece.

Anunciar descontinuação no changelog tem taxa de leitura próxima de zero, porque quem mantém a integração raramente é quem assinou a lista de novidades. O sinal precisa viajar junto com a resposta que o cliente já está consumindo, e existem dois cabeçalhos padronizados para isso: Deprecation, que diz que o recurso está descontinuado, e Sunset, que diz a data em que ele deixa de existir. Ambos aceitam data em formato HTTP, e a combinação com um link para a documentação da migração é o mínimo que funciona.

// contract/descontinuacao.js
// Emite os sinais de descontinuacao junto da propria resposta e registra
// que o cliente recebeu o aviso. O registro e o que permite dizer, no dia
// da remocao, ha quanto tempo aquele cliente especifico esta avisado.

const avisosEntregues = new Map(); // clienteId -> { primeiro, ultimo, total }

export const aplicarDescontinuacao = ({
  res,
  clienteId,
  campo,
  sunsetISO,
  docUrl,
}) => {
  const sunset = new Date(sunsetISO);

  res.setHeader('Deprecation', 'true');
  res.setHeader('Sunset', sunset.toUTCString());
  res.setHeader('Link', '<' + docUrl + '>; rel="deprecation"; type="text/html"');
  res.setHeader(
    'Warning',
    '299 - "campo ' + campo + ' sera removido em ' + sunsetISO + '"',
  );

  const agora = Date.now();
  const registro = avisosEntregues.get(clienteId) || {
    primeiro: agora,
    ultimo: agora,
    total: 0,
  };
  registro.ultimo = agora;
  registro.total += 1;
  avisosEntregues.set(clienteId, registro);
};

// Criterio objetivo para autorizar a contracao de um cliente especifico:
// ele precisa ter recebido o aviso por tempo suficiente e ter parado de
// usar o campo. Um dos dois sozinho nao basta.
export const podeContrair = ({ clienteId, usosRecentes, diasMinimos = 90 }) => {
  const registro = avisosEntregues.get(clienteId);
  if (!registro) {
    return { pode: false, motivo: 'cliente nunca recebeu o aviso' };
  }

  const diasAvisado = (Date.now() - registro.primeiro) / 86400000;
  if (diasAvisado < diasMinimos) {
    return { pode: false, motivo: 'avisado ha ' + Math.floor(diasAvisado) + ' dias' };
  }
  if (usosRecentes > 0) {
    return { pode: false, motivo: usosRecentes + ' usos na janela' };
  }
  return { pode: true, diasAvisado: Math.floor(diasAvisado) };
};

A função que decide se pode contrair é onde a política vira código auditável. Ela exige duas condições independentes: o cliente foi avisado por tempo suficiente e o cliente parou de usar o campo. Exigir só a primeira é o modelo do prazo anunciado, que quebra quem não leu. Exigir só a segunda é o modelo da medição pura, que quebra quem tem sazonalidade. Juntas, as duas produzem uma decisão por cliente e não por endpoint, e é por cliente que o incidente acontece.

A instrumentação da evolução de contrato falha de um jeito específico: as métricas ficam boas justamente porque o campo antigo continua sendo servido, e a ausência de erro é lida como ausência de dependência. Os três alertas abaixo medem coisas que mudam antes do incidente e não depois.

O terceiro alerta é o que evita o erro que este artigo inteiro tenta prevenir. Um cliente que não aparece na janela de trinta dias não é um cliente que migrou, é um cliente sobre o qual você não tem informação. Separar esses dois grupos no relatório transforma a decisão de remover de um palpite baseado em silêncio em uma decisão baseada em evidência, e é a diferença entre encerrar uma migração e descobrir na segunda-feira do fechamento que o parceiro de 2021 nunca leu o changelog.