O problema das chaves de API que nunca expiram
Uma chave emitida anos atrás, nunca trocada e ainda válida hoje não é uma conveniência. É um risco que ninguém examina de verdade há anos.
Contra formatos de resposta proprietários
Pergunte por que uma API retorna um modelo de objetos aninhado e personalizado em vez de uma estrutura JSON simples e plana, e a resposta honesta raramente é técnica. Um formato proprietário não torna uma consulta mais rápida nem mais precisa. Ele torna a resposta mais difícil de substituir, porque cada nome de campo, cada nível de aninhamento e cada código de status personalizado que o seu código aprende a tratar é um pequeno conhecimento específico do fornecedor embutido na sua aplicação.
Achamos que isso está invertido. Um formato de resposta deveria descrever os dados, não o fornecedor. Coordenadas, endereços, deslocamentos e altitudes são os mesmos conceitos, independentemente de quem responde à requisição, então o formato retornado para eles deveria ser tão simples quanto os próprios conceitos. É também por isso que 17 dos nossos hosts retornam exatamente o formato de resposta da API de outro provedor: os dados são nossos, mas o formato é um que o seu código talvez já entenda, porque, para começo de conversa, não cabe a nós inventá-lo.
Formatos proprietários também costumam acumular esquisitices que não têm nada a ver com os dados em si e tudo a ver com a história interna do provedor. Um campo é renomeado por causa de uma migração interna e o nome antigo fica como um alias obsoleto que ninguém quer remover. Um status é representado como string em um endpoint e como código numérico em outro, porque foram criados por equipes diferentes com anos de diferença. Nada disso é malicioso. É apenas o que acontece quando um formato nunca é projetado com base em um padrão externo, só com base no código em evolução da própria empresa.
A solução não é complicada: escolha uma estrutura simples, documente-a uma vez e mantenha-a estável. Fazemos isso em nossos próprios endpoints nativos e vamos um passo além com os hosts de compatibilidade, reproduzindo exatamente o formato de outro provedor para que um código que já interpreta esse formato não precise de nenhuma mudança além de uma URL base e uma chave. Esse compromisso é maior do que parece. Significa que, quando o formato que reproduzimos tem um nome de campo estranho ou uma escolha de aninhamento inconsistente, mantemos a estranheza, porque todo o valor do host de compatibilidade está na fidelidade, não na melhoria.
Às vezes, um formato proprietário é defendido como uma forma de dar ao provedor espaço para adicionar dados mais ricos com o tempo. Não achamos que a riqueza exija um formato desconhecido. Campos opcionais, como altitude ou detalhes de ameaça de IP, podem ficar ao lado de uma resposta padrão como acréscimos, e não como substituições, para que quem não os pede nunca precise contorná-los ao interpretar a resposta, e quem os pede os receba sem aprender um novo formato.
Nada disso é realmente sobre formatação de JSON como preferência técnica. É sobre quem arca com o custo de uma decisão de formato. Um formato proprietário coloca esse custo em cada cliente que um dia precisar ler a resposta. Um formato simples ou reproduzido o coloca em nós, no trabalho de design de manter tudo previsível. É aí que o custo deve ficar.