Insights sobre versionamento de APIs

Neste artigo, faço uma pesquisa sobre como algumas das principais APIs do mercado tratam o assunto versionamento. Para conhecer alguns conceitos básicos sobre versionamento, recomendo primeiro a leitura do capítulo sobre versionamento no Guia de Design REST.

No quadro abaixo, listo algumas APIs independente do segmento, idade, qualidade da modelagem ou aderência ao REST. Observe como cada uma das empresas optou por versionar suas APIs.

Com base no quadro acima, podemos observar alguns pontos:

Preferência por path parameter e query parameter

Apesar de ter buscado por APIs diversas, nenhuma delas optou pelo versionamento via host ou header. O Vimeo foi o único a adotar a abordagem com content-type. A preferência geral foi por utilizar path parameter (na estrutura da URL) ou passar como query parameter.

Foram utilizadas Major somente, Major.Minor e datas

Em ordem crescente, as empresas preferiram optar por versionar considerando apenas o Major, Major.Minor e uma minoria com data.

Adotam uma única forma de versionar

A maioria optou por um único ponto para versionar a API (path parameter ou query). Apenas a API do Four Square que optou por colocar a Major na URL e opcionalmente, uma versão específica via query string.

Algumas endereçaram versões preview, beta e builds recorrentes

Apesar de menos frequente, algumas strings de versionamento endereçam builds recorrentes, como weekly, quarterly como na Google Maps em Javascript; v1beta1 na Google Datastore e 2017-10-01-preview na Azure Sql Databases.

E o Oscar vai para "versão MAJOR na URL"

Quando falamos versionamento semântico, alterações em Minor e Path não devem fazer com que quem já consome a versão tenha qualquer problema por quebra de contrato, ou seja, nenhum campo não obrigatório passa a ser obrigatório e nenhum campo é removido. Neste tipo de alteração, são apenas adicionados novos campos ou feitas alterações em metadados. Assim, pequenas evoluções podem ser feitas na API e notificadas aos desenvolvedores, no entanto, sem demandar que atualizações sejam obrigatoriamente feitas nos seus clientes.

Entendo que clientes que venham a "quebrar" por conta da adição de novos campos, provavelmente fizeram o consumo da API de forma atípica, pra não falar errada, talvez, processando manualmente o payload e buscando os campos por posição, por exemplo. Martin Fawler em TolerantReader reforça conceitos do comportamento que é esperado de um consumidor de serviços.

Outro ponto a ser considerado é que, por mais que não se quebre diretamente o contrato, quem produz a API pode optar por incrementar uma MAJOR em casos raros, mas possíveis, como aumento considerável do tamanho ao payload, aumento considerável do tempo de processamento, alteração nas regras de quantidade de registros retornados etc.

Open Banking: E quando o modelo é definido por uma entidade externa?

- Abordagem 1: versão MAJOR apenas e flexibilidade timing da migração.

No cenário de Open Banking, por exemplo, em que o contrato é definido por uma entidade externa e os clientes e servidores devem respeitá-lo, também seria possível manter o versionamento apenas com a MAJOR na URL.

Imagine o cenário de um contrato como o de baixo:

Agora, segue um exercício de cliente e servidor implementando em "tempos" diferentes e sem que um impacte no outro.

A vantagem desta abordagem é que permite que tanto o cliente, quanto servidor possam implementar as versões definidas pela entidade externa, cada um no seu tempo, independentemente se a outra parte da comunicação já o fez.

Imagina um app de financiamento de veículos que integraria com centenas de fornecedores bancários, seria desejável esse app poder atualizar a versão do seu software uma única vez quando o Open Banking definir uma nova versão, independentemente to timing de cada um dos fornecedores.

O que garantirá que as peças "se encaixem" será o contrato bem especificado com tamanho máximo, mínimo, tipo de dado, expressão regular, exemplos e boas descrições, de forma que a implementação em ambos os lados não tragam elementos surpresa quando estiver em produção.

O que garantirá a aderência do software aos contratos são as ferramentas já fornecidas pelas disciplinas de testes e qualidade de software conhecidas pelo mercado.

- Abordagem 2: versão MAJOR.MINOR e inflexibilidade no timing da migração.

Opcionalmente, se partirmos do princípio de que as práticas acima não serão seguidas, podemos utilizar a versão específica MAJOR.MINOR na URL, isso reduz o risco de alguma quebra do cliente, pois o servidor passa a ofertar sempre 'n' versões do software, no entanto, o cliente fica dependente do servidor implementar primeiro a versão para depois ele poder consumir.

As URLs, neste caso ficariam assim:

• /cadastros/v1.0/clientes
• /cadastros/v1.1/clientes
• /cadastros/v2.1/clientes

- Abordagem 3: versão MAJOR ou MAJOR.MINOR e flexibilidade no timing da migração.

Neste modelo, podemos ter 4 URLs:

• /cadastros/v1/clientes
• /cadastros/v1.0/clientes
• /cadastros/v1.1/clientes
• /cadastros/v1.2/clientes

Assim ofereceríamos flexibilidade aos clientes, dado que ele escolhe se prefere trabalhar com a abordagem 1 ou a 2.

Quando o cliente chamar a URL v1, ele sempre trará a implementação mais recente existente da versão 1. Logo, o comportamento seria o mesmo da abordagem 1, no entanto, além da v1, o servidor disponibilizaria as v1.0, v1.1 e v1.2 para aqueles clientes que prefiram a segurança de ter um contrato congelado no tempo, mas com o trade-off de esperar o servidor implementar a versão.

Conclusão

Sobre Open Banking, penso no cliente que é um APP e precisará acessar ao mesmo tempo 'n' implementações de bancos diferentes. Acredito que ele prefira a flexibilidade de implementar uma única vez a capacidade de ler a nova versão e colher os benefícios de novos atributos o quanto antes, independente de os seus vários fornecedores de informação já estarem preparados para disponibilizá-las. Por isso, gosto da abordagem 3, que me parece atender a qualquer um dos cenários. Inclusive daquele que optar por aguardar todos os fornecedores disponibilizarem a versão nova.

Sobre os modelos de versionamento de forma geral, talvez com um número bem maior de APIs, outros insights poderiam ter aparecido, no entanto, não me surpreendeu que após este pequeno o levantamento, não tenha aparecido nada de muito novo, senão o que já é recorrente em guias de boas práticas. Ou seja, já existe uma convergência no mercado para alguns modelos principais.