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.
Em defesa de um versionamento de API chato e estável
Um provedor que anuncia uma nova versão principal da API geralmente está anunciando, a todos os clientes com uma integração existente, um projeto que eles não pediram. Mesmo uma mudança incompatível bem comunicada significa que alguém precisa reservar tempo para ler um guia de migração, atualizar o tratamento das requisições ou respostas, testar e implantar, em um prazo definido pelo roadmap do provedor, e não por qualquer coisa que esteja acontecendo no produto do próprio cliente.
Achamos que a estabilidade de uma API merece ser tratada como um objetivo de design por si só, e não como falta de ritmo. Um formato de resposta, depois de publicado, deve continuar significando o que significava quando um desenvolvedor começou a usá-lo. Novos campos podem ser adicionados como acréscimos opcionais, da mesma forma que altitude, ameaça de IP e detalhes de rede são extras opcionais sobrepostos às respostas padrão, e não reestruturações forçadas delas. O que não deve acontecer em silêncio é um campo existente mudar de significado, um código de status ser reaproveitado para outra coisa ou um formato ser reestruturado sob o mesmo número de versão.
Parte do motivo pelo qual mudanças incompatíveis acontecem com tanta frequência neste setor é que elas são baratas para o provedor e caras para o cliente, e os dois lados raramente negociam esse desequilíbrio diretamente. Lançar um modelo interno mais limpo é uma conquista de engenharia legítima para a equipe do provedor. Ela vira um fardo no momento em que obriga cada integração a jusante a mudar em resposta, em um cronograma que o provedor controla e o cliente não.
Isso não significa que uma API nunca deva mudar. Significa que as mudanças devem ser aditivas sempre que possível e, quando uma mudança incompatível real for inevitável, ela deve ser rara o bastante para que o cliente possa confiar que o formato com que ele construiu a integração ainda vai funcionar meses ou anos depois, e não algo contra o qual ele precise se defender acompanhando um changelog. Estabilidade não é o mesmo que estagnação. É uma promessa de que o trabalho de integração de hoje não tem uma data de validade anexada da qual ninguém avisou você.
Também temos um motivo egoísta para manter essa posição, além da boa vontade dos clientes. Cada host de compatibilidade que operamos depende de reproduzir fielmente o formato de outro provedor ao longo do tempo, o que só funciona se os formatos, depois de reproduzidos, forem alvos estáveis em que valha a pena confiar. Uma empresa que trata a própria superfície de API como descartável, para ser redesenhada sempre que for conveniente, é uma empresa cujas garantias de compatibilidade também não são garantias de verdade. A estabilidade precisa ser um hábito que vale em todo lugar, ou ela não vale de verdade em lugar nenhum.
Sem surpresas não é uma crítica aqui. Uma versão de uma API que ainda funciona exatamente como funcionava quando você a integrou pela primeira vez, anos depois, não é prova de que nada melhorou. É prova de que as melhorias aconteceram de maneiras que não exigiram que você as percebesse, e esse é justamente o objetivo de uma boa disciplina de versionamento.