Esta é uma pergunta boa e complicada. O tópico de design de URI é ao mesmo tempo a parte mais importante de uma API REST e , portanto, um compromisso potencialmente de longo prazo para os usuários dessa API .
Desde a evolução de um aplicativo e, em menor grau, sua API é um fato da vida e é ainda semelhante à evolução de um produto aparentemente complexo como uma linguagem de programação, o design do URI deve ter menos restrições naturais e deve ser preservado ao longo do tempo . Quanto maior a vida útil do aplicativo e da API, maior o comprometimento com os usuários do aplicativo e da API.
Por outro lado, outro fato da vida é que é difícil prever todos os recursos e seus aspectos que seriam consumidos por meio da API. Felizmente, não é necessário projetar toda a API que será usada até o Apocalypse . É suficiente definir corretamente todos os pontos finais de recursos e o esquema de endereçamento de cada recurso e instância de recurso.
Com o tempo, pode ser necessário adicionar novos recursos e novos atributos a cada recurso específico, mas o método que os usuários da API seguem para acessar determinados recursos não deve mudar assim que um esquema de endereçamento de recursos se tornar público e, portanto, final.
Esse método se aplica à semântica de verbos HTTP (por exemplo, a PUT sempre deve atualizar / substituir) e aos códigos de status HTTP suportados nas versões anteriores da API (eles devem continuar a funcionar para que os clientes da API que trabalharam sem intervenção humana possam continuar trabalhando) Curtiu isso).
Além disso, como a incorporação da versão da API no URI interromperia o conceito de hipermídia como o mecanismo do estado do aplicativo (declarado na dissertação de doutorado de Roy T. Fieldings) por ter um endereço de recurso / URI que mudaria ao longo do tempo, eu concluiria que a API as versões não devem ser mantidas nos URIs de recursos por um longo período de tempo, o que significa que os URIs de recursos dos quais os usuários da API podem confiar devem ter links permanentes .
Claro, é possível incorporar a versão da API no URI base, mas apenas para usos razoáveis e restritos, como depurar um cliente da API que funcione com a nova versão da API. Essas APIs com versão devem ter um tempo limitado e estar disponíveis apenas para grupos limitados de usuários da API (como durante betas fechados). Caso contrário, você se compromete onde não deveria.
Algumas reflexões sobre a manutenção de versões da API com data de validade. Todas as plataformas / linguagens de programação comumente usadas para implementar serviços da Web (Java, .NET, PHP, Perl, Rails, etc.) permitem a ligação fácil dos pontos finais dos serviços da Web a um URI base. Dessa forma, é fácil reunir e manter uma coleção de arquivos / classes / métodos separados em diferentes versões da API .
No POV dos usuários da API, também é mais fácil trabalhar e vincular-se a uma versão específica da API quando isso é óbvio, mas apenas por tempo limitado, ou seja, durante o desenvolvimento.
No ponto de vista do mantenedor da API, é mais fácil manter versões diferentes da API em paralelo, usando sistemas de controle de origem que funcionam predominantemente em arquivos como a menor unidade de versão (código fonte).
No entanto, com as versões da API claramente visíveis no URI, há uma ressalva: também é possível objetar essa abordagem, pois o histórico da API se torna visível / aparente no design do URI e, portanto, está sujeito a alterações ao longo do tempo, o que contraria as diretrizes do REST. Concordo!
A maneira de contornar essa objeção razoável é implementar a versão mais recente da API no URI base da API sem versão. Nesse caso, os desenvolvedores de clientes da API podem optar por:
desenvolva contra o mais recente (comprometendo-se a manter o aplicativo protegendo-o de eventuais alterações na API que possam interromper seu cliente de API mal projetado ).
vincular a uma versão específica da API (que se torna aparente), mas apenas por um tempo limitado
Por exemplo, se a API v3.0 é a versão mais recente da API, os dois seguintes devem ter aliases (ou seja, comportar-se de forma idêntica a todas as solicitações de API):
http: // shonzilla / api / customers / 1234
http: // shonzilla / api / v3.0 / customers / 1234
http: // shonzilla / api / v3 / customers / 1234
Além disso, os clientes da API que ainda tentam apontar para a API antiga devem ser informados a usar a versão anterior mais recente da API, se a versão da API que eles estão usando estiver obsoleta ou não for mais suportada . Portanto, acesse qualquer um dos URIs obsoletos como estes:
http: // shonzilla / api /v2.2 / customers / 1234
http: // shonzilla / api /v2.0 / customers / 1234
http: // shonzilla / api / v2 / customers / 1234
http: // shonzilla / api /v1.1 / customers / 1234
http: // shonzilla / api / v1 / customers / 1234
deve retornar qualquer um dos códigos de status HTTP 30x que indicam o redirecionamento usado em conjunto com o Location
cabeçalho HTTP que redireciona para a versão apropriada do URI do recurso que permanece como este:
http: // shonzilla / api / customers / 1234
Há pelo menos dois códigos de status HTTP de redirecionamento apropriados para cenários de versão da API:
301 Movido permanentemente, indicando que o recurso com um URI solicitado é movido permanentemente para outro URI (que deve ser um link permanente de instância de recurso que não contém informações da versão da API). Esse código de status pode ser usado para indicar uma versão obsoleta / não suportada da API, informando ao cliente da API que um URI de recurso com versão foi substituído por um link permanente de recurso .
302 encontrado indicando que o recurso solicitado está temporariamente localizado em outro local, enquanto o URI solicitado ainda pode ser suportado. Esse código de status pode ser útil quando os URIs sem versão estão temporariamente indisponíveis e que uma solicitação deve ser repetida usando o endereço de redirecionamento (por exemplo, apontando para o URI com a versão APi incorporada) e queremos dizer aos clientes para continuar usando (ou seja, o permalinks).
outros cenários podem ser encontrados no capítulo Redirection 3xx da especificação HTTP 1.1