API REST versão (versão apenas a representação, e não o próprio recurso)

StackOverflow https://stackoverflow.com/questions/2024600

  •  19-09-2019
  •  | 
  •  

Pergunta

Eu tive uma olhada Melhores práticas para a API de versões? , mas não sou bastante convencido da resposta, por isso estou pergunta a parte de versões novamente com um exemplo mais específico. Estou tendo dois URIs (um com controle de versão como parte da URI e um sem): 

http://xxxx/v1/user/123    -> favored solution in discussed thread
http://xxxx/user/123

Eu estou tendo minhas dúvidas se a primeira ligação expressa a idéia de REST. Acho http://xxxx/v1/user/123 confuso, uma vez que sugere que haverá uma api-versão superior um dia como http://xxxx/v2/user/123. Mas isso não faz sentido em termos de REST, a própria versão da API é HTTP 1.0 ou 1.1, que já é enviado dentro do pedido HTTP. Este recurso REST centric vista difere muito de outros api-interfaces como SOAP ou Java-interfaces (onde é comum ter api-versões em nomes qualificados).

em repouso a única coisa que faz sentido de versão é a representação desse recurso (por exemplo, novos campos são adicionados ou removidos). Este versionamento pertence à parte da negociação de conteúdo como: 

http://xxx/user/123 + HTTP 'Accept' Header -> Content negotation through header
http://xxx/user/123?v=1                    -> for perma-links/hyperlinks

Pode-se também argumentar que tal versão de conteúdo de negociação poderia ser parte da URI dentro do caminho, mas acho que é um contra-senso, porque você pode acabar-se com diferentes URIs para o mesmo recurso e têm que manter redirecionamentos em algum ponto.

Para resumir-up: Em URIs REST não há-api versionamento, apenas a versões de representação do recurso. Representação versão-info pertence a conteúdo de negociação (como queryParam ou HTTP 'Aceitar').

O que você acha? Em que as coisas se você não concordar / concorda?

Foi útil?

Solução

Eu concordo completamente; um URI expressa a identidade, a identidade não muda quando uma nova versão é introduzida. Pode haver novos URIs para conceitos adicionais, é claro, e URIs existentes pode redirecionar ... mas incluindo um "v2" no URI cheira RPCish para mim.

Note que este não tem nada a ver com REST, realmente, a partir de uma perspectiva RESTO é todos os caracteres apenas.

Outras dicas

Você pode ouvir um cabeçalho de solicitação HTTP X-API-Version. Se existe o cabeçalho, em seguida, o servidor deve usar essa versão da API. Se o cabeçalho não existe, o servidor pode utilizar a versão mais recente da API. 

> GET /user/123 HTTP/1.1
> Host: xxx
> X-API-Version: >=1.5.1, <2.0.0
> Accept: application/json
>

< HTTP/1.1 200 OK
< X-API-Version: 1.6.12
<
< { "user": { "id": 123, "name": "Bob Smith" } }
<

Por que vale a pena, eu concordo com você Manuel. Você pode ver o meu raciocínio nesta questão Como versão URIs REST

Existem muitas pessoas que parecem discordar, mas eu não me preocuparia. Qual a sua aparência URL como realmente não tem um grande impacto sobre o seu cliente, desde que você respeitar a restrição de hipertexto.

Eu concordo que você não quer ver versões nos URIs de recursos apresentados em sua API. Isso os torna não "cool". Também concorda que o que é representações que são mais susceptíveis de mudança.

No entanto, não levante a questão do que acontece quando você alterar o conteúdo de uma representação particular. Por exemplo, se a sua representação JSON original de um frobnitz é 

{"x": "bam", "y": "hello"}

e você quer adicionar um campo de "z" você pode sentir que o cliente deve ter alguma consciência de que estamos agora na versão 2 de algum tipo de esquema de dados.

Eu não tenho certeza sobre isso. Eu acho que você tem algumas opções:

  • Faça seus clientes flexível diante de uma suavemente mudança representações. No exemplo acima, nós ainda estamos gerando um dicionário JSON.
  • Se você deve, colocar uma versão na própria representação (a versão campo neste exemplo). Ao fazer isso você está declarando efetivamente uma sub-representação no tipo de conteúdo JSON. Eu acho que é muito limitante embora.
  • Use seus próprios tipos MIME e versão deles: application / x-meu-especial-json1.0, application / x-meu-especial-json1.1. Isso permite que você versão suas representações independentemente um do outro. Mais uma vez, com um presente que você está fazendo uma demanda significativa em seus clientes para saber o que está acontecendo.

Em geral, eu acho que você deseja otimizar sua API e suas representações para clientes que você não tenha inventado a si mesmo; aqueles que as outras pessoas vão criar em cima de descobrir seus recursos. Eu acredito que esta é útil, mesmo no caso quando você está fazendo algo que é privado porque constrói em uma restrição de design útil que vai ajudar a tornar o sistema mais robusto.

http: // xxxx / v1 / user / 123 confusa uma vez que sugere que há será uma API de versão superior um dia como http: // xxxx / v2 / user / 123

Ele não sugere que -. Contudo, você tem essa capacidade no futuro

Mas isso não faz sentido em RESTO termos, a própria versão da API é HTTP 1.0 ou 1.1, que já é enviado dentro do pedido HTTP.

A versão de sua API e a versão do HTTP que você está usando para fazer solicitações não tem que ser igual.

Pode-se também argumentar que tal versão conteúdo de negociação poderia ser parte de a URI dentro do caminho, mas acho que é um contra-senso, porque você pode acabam-se com diferentes para a URIs mesmo recurso e têm que manter redirecionamentos em algum ponto.

Sua aprovação para ter a versão como um parâmetro URI como você demonstrou.

http: // xxx / user / 123 v = 1 -> para perma -links / hiperlinks

Outra abordagem poderia ser a dizer que "uma representação tem múltiplas APIs": 

http://xxx/user/123/api/1.json

E se você quiser, você pode retornar a representação utilizando a mais recente API ao solicitar assim: 

http://xxx/user/123.json

Pessoalmente eu gosto de outras soluções melhores, mas esta é uma outra abordagem que eu não vi ainda sugerido aqui.

Para REST, que a maioria das respostas esquecer é o elemento de dados. Presumo share ainda múltipla versão da API que mesmo camada de dados. Isto significa que a camada de forças de dados que você pense de uma maneira compatível com versões anteriores. Grandes mudanças que têm de ser feito só são possíveis se o seu API muda de forma compatível com versões anteriores. Na prática isto significa que propriedades adicionais são adicionados silenciosamente para suas entidades ao usar depreciação por data no documento API para indicar quando algo vai ser removido. Idealmente, você usar um esquema de registo com endereço de e-mail de seus usuários-chave de API, para que possa notificá-los sobre depreciação dentro de um determinado espaço (a la Facebook) .Portanto, eu não acho que você precisa especificar um em qualquer lugar versão.

Licenciado em: CC-BY-SA com atribuição
Não afiliado a StackOverflow
scroll top