O versionamento de APIs Web adicionando a versão na URI ou usando medias types versionados não funciona na Internet aberta. O que se faz necessário são contratos que evoluam com as mudanças requeridas, Sebastien Lambla em uma apresentação recente descreveu várias maneiras para eliminar a necessidade de versões.
Para Sebastien Lambla, consultor e defensor da arquitetura REST, um motivo comum para o controle de versão de APIs Web se deve aos contratos usados para evitar a quebra de aplicações clientes. É necessário permitir que clientes e servidores sejam alterados de forma independente, e também ser capaz de comunicar as alterações da API para os desenvolvedores de clientes.
Uma forma de controle de versão é adicionar a versão para o URI:
http://api.equestrian.magic/v1/
Um problema quando a URI para um recurso muda é que o recurso pode não ser mais encontrado com a URI antiga, a menos que redirecionamentos sejam utilizados. Sebastien Lambla enfatiza que a URI de um recurso nunca deve mudar, mas com a nova versão o recurso terá duas URIs diferentes, sendo cada URI uma coisa diferente sem a possibilidade de relacioná-las entre si.
Uma alternativa é adicionar a versão para o nome de domínio:
http://v1.api.equestrian.magic/
Desde que as URIs sejam opacas, na prática é criado um novo sistema. Com múltiplos sistemas e modelos, mas ainda visando o mesmo modelo de dados, isto torna a manutenção cada vez mais difícil.
A terceira alternativa é versionar os media types, que de acordo com Lambla, é o menos comum na web hoje em dia, e mais comum nas empresas. Esta alternativa é baseada na negociação de conteúdo e adiciona um número de versão no media type em Accept e cabeçalhos de Content-Type:
application/vnd.equestrian.ponies.v1+xml
Sebastien Lambla lembra que embora sejam versões diferentes, são na realidade recursos diferentes e que o uso de media types para a mesma URI quebra a identificação dos recursos. Ele se refere a Roy Fielding na sua afirmação:
Sugerimos que os proprietários de recursos só usem a verdadeira negociação de conteúdos (sem redirecionamento) quando a única diferença entre os formatos é de natureza mecânica.
Para Sebastien Lambla nenhuma dessas técnicas de controle de versão funciona na Internet aberta. É necessário algo que possa evoluir, usando contratos que possam evoluir suavemente para atender as mudanças necessárias. Para Sebastien Lambla esse é um problema bem compreendido que refere-se a web; com muitos milhões de microserviços que tem funcionado muito bem por vinte e cinco anos sem grandes problemas e sem nenhum controle de versão, com exceção ao protocolo HTTP.
O primeiro pilar para contratos que evoluem é a compatibilidade retroativa. Sebastien Lambla usa o HTML como exemplo, onde existem vários elementos que tem o uso desencorajado, porém ainda são suportados pelos clientes, já que não é possível atualizar todos os sites do mundo. Os mesmos princípios devem ser aplicados em uma API, que evolui e ainda suporta os formatos antigos.
O segundo pilar é compatibilidade futura. Para conseguir atingir isto, você tem que ignorar o desconhecido e o que não é compreendido. Lambla se refere ao CSS como exemplo, pois novos atributos podem ser manipulados sem problemas. Para atingir esse objetivo, regras de recuperação de falhas são usadas para tratar atributos desconhecidos, uma boa estratégia para conseguir pontos de extensão.
XML ainda é vastamente utilizado, e muitas vezes com esquemas XML. Para prover a capacidade de evolução e necessária flexibilidade em conteúdo, e Lambla não recomenda validar esquemas em servidores e em clientes. Em vez disso, apenas encontrar os elementos e atributos necessários e ignorar o resto.
Para evitar versionamento é necessário suportar todas as funcionalidades, mas não é possível manter todas as alterações das APIs para sempre. Velhas funcionalidades que são raramente utilizadas podem ser removidas. Para saber quando elas podem ser removidas, deve-se usar métricas de uso, podendo então decidir que, quando o uso apresenta-se abaixo de, 1% por exemplo, a funcionalidade pode ser removida.