É isso API REST Realmente RPC? Roy Fielding parece pensar assim
https://stackoverflow.com/questions/1164154
italiano
english
français
española
中国
日本の
العربية
Deutsch
한국어
Português
RussianPergunta
Uma grande quantidade do que eu achava que sabia sobre REST é aparentemente errado - e eu não estou sozinho. Esta questão tem um longo lead-in, mas parece ser necessário porque a informação é um pouco dispersos. A questão real vem no final, se você já está familiarizado com este tema.
Desde o primeiro parágrafo do APIs REST obrigação de Roy Fielding ser impulsionado pelo hipertexto , é bastante claro que ele acredita que seu trabalho está sendo amplamente mal interpretado:
Eu estou ficando frustrado pelo número de pessoas chamando qualquer HTTP baseado em uma interface API REST. O exemplo de hoje é o SocialSite API REST . Isso é RPC. Ela grita RPC. Não é tanto o acoplamento em exposição que deve ser dada uma classificação X.
Fielding continua a listar vários atributos de uma API REST. Alguns deles parecem ir contra ambos prática comum e conselho comum no SO e outros fóruns. Por exemplo:
-
A API REST deve ser introduzido com nenhum conhecimento prévio para além da URI inicial (marcador) e conjunto de tipos de mídia padronizados que são apropriados para o público-alvo (ou seja, deverá ser entendido por qualquer cliente que pode usar o API). ...
-
A API REST não deve definir nomes fixos de recursos ou hierarquias (um acoplamento óbvia de cliente e servidor). ...
-
A API REST deve gastar quase todo o seu esforço descritivo na definição do tipo de mídia (s) usado para representar recursos e dirigir o estado do aplicativo, ou na definição de nomes de relações prolongadas e / ou mark-up para hipertexto habilitado tipos de mídia padrão existente. ...
A idéia de "hipertexto" desempenha um papel central - muito mais do que a estrutura URI ou o HTTP verbos média. "Hypertext" é definido em um dos comentários:
Quando eu [Fielding] dizer hipertexto, quero dizer a apresentação simultânea de informações e controles de tal forma que a informação se torna a affordance através do qual o usuário (ou autômato) obtém escolhas e ações seleciona. Hipermídia é apenas uma expansão do que significa texto para incluir âncoras temporais dentro de um fluxo de mídia; a maioria dos pesquisadores caíram a distinção.
Hypertext não precisa ser HTML em um browser. As máquinas podem seguir os links quando eles entendem os tipos de formato e de relacionamento de dados.
Eu estou supondo que, neste ponto, mas os dois primeiros pontos acima parecem sugerir que a documentação da API para um recurso de Foo que se parece com os seguintes leva a forte ligação entre cliente e servidor e não tem lugar em um sistema RESTful.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
Em vez disso, um agente deve ser forçado a descobrir os URIs para todos os Foos, por exemplo, a emissão de um pedido GET contra / foos. (Esses URIs pode vir a seguir o padrão acima, mas isso não vem ao caso.) A resposta usa um tipo de mídia que é capaz de transmitir como acessar cada item eo que pode ser feito com ele, dando origem ao terceiro ponto acima . Por esta razão, a documentação API deve se concentrar no explicando como interpretar o hipertexto contido na resposta.
Além disso, cada vez que um URI a um recurso de Foo é solicitada, a resposta contém todas as informações necessárias para um agente para descobrir como proceder, por exemplo, o acesso a recursos do pai associado e através de seus URIs, ou através de uma acção após a criação / exclusão de um recurso.
A chave para todo o sistema é que a resposta consiste em hipertexto contido em um tipo de mídia que se transmite às opções do agente para continuar. Não é diferente a forma como um navegador funciona para os seres humanos.
Mas este é apenas o meu melhor palpite neste momento particular.
Fielding colocaram um de acompanhamento em que ele respondeu às críticas de que sua discussão foi muito abstrato, carente de exemplos, e rico em jargão:
Outros vão tentar decifrar o que tenho escrito de maneiras que são mais direta ou aplicável a alguma preocupação prática de hoje. Eu provavelmente não vai, porque eu sou de luta muito ocupado com o próximo tópico, preparando-se para uma conferência, escrevendo outro padrão, viajar para algum lugar distante, ou apenas fazer as pequenas coisas que deixe-me sentir que eu tenho eu ganho meu salário.
Então, duas perguntas simples para os especialistas em REST lá fora, com uma mentalidade prática: como você interpreta o que Fielding está dizendo e como você colocá-lo em prática quando documentando / implementação de APIs de REST
Editar: esta pergunta é um exemplo de como ele pode ser duro para aprender alguma coisa, se você não tem um nome para o que você está falando. O nome neste caso é "Hipermídia como motor do Estado de Aplicativos" (HATEOAS).
Solução
Eu acho que sua explicação cobre principalmente. URIs são identificadores opacos que deve, em sua maior parte, não ser comunicadas além do marcador URI que é usado pelo agente de usuário para acessar o aplicativo.
Quanto à documentação, esta questão tem sido feito bastante algumas vezes. Você documentar o seu tipo de mídia, juntamente com os controles de hiperlink que ela contém (links e formulários), e o modelo de interação se assim o desejar (ver AtomPub).
Se você documentar os URIs ou como construí-los, você está fazendo errado.
Outras dicas
A sua interpretação parece correta para mim. Eu acredito que as restrições de Fielding pode ser aplicado praticamente.
Eu realmente gostaria de ver alguém publicar alguns bons exemplos de como documentar uma interface REST. Há tantos exemplos pobres, têm alguns dos mais válidos para os usuários apontam para seria muito valioso.
I foram à procura de um bom exemplo de uma API escrita após a HATEOAS e teve problemas um achado (eu achei tanto a API SunCloud e coisas AtomPub difícil de aplicar a uma situação API "normal"). Então, eu tentei fazer um exemplo realista no meu blog que seguiu o conselho Roy Fieldings sobre o que significa ser uma implementação de descanso adequado. Achei muito difícil chegar com o exemplo, apesar do fato de que ele é bastante simples, em princípio (apenas confuso quando se trabalha com uma API em oposição a uma página web). Eu tenho o que Roy estava tomando problema com e concordar, é apenas uma mudança de mentalidade para implementar adequadamente para uma API.
Dê uma olhada: Exemplo API usando Resto
A única exceção a dar instruções sobre como construir URIs é que é permitido enviar um modelo URI na resposta hipertexto, com campos para ser substituído automaticamente pelo cliente, usando outros campos no hipertexto. Isso geralmente não acabam salvando muita largura de banda embora desde compressão gzip vai lidar com as partes repetidas de URIs bem o suficiente para não se preocupar com isso.
Algumas boas discussões sobre REST e o HATEOAS relacionada:
Para os interessados, eu encontrei um exemplo detalhado de HATEOAS na prática no Sun Nuvem API .
A única coisa que a maioria das pessoas errar é que (pelo menos eu acho) no mundo do resto você não documentar sua "interface REST", o que você documento é um tipo de mídia, independentemente do seu servidor ou serviço.
Absolutamente correto. Eu notar também que que os modelos URI são perfeitamente bem dentro de um aplicativo RESTful desde que os padrões são a partir de documentos recebidos do servidor (OpenSearch ser um exemplo adequado). Para modelos URI, você documento onde eles estão sendo usados ??e que os espaços reservados esperados no modelo são, mas não os modelos de si mesmos. Ligeiramente ao contrário do que Wahnfrieden disse, esta não é uma exceção.
Por exemplo, no meu trabalho, temos um sistema interno de gerenciamento de domínio, eo serviço especifica documento dois modelos URI: um para produzir um melhor palpite URI de um recurso de domínio, e outra para a construção de um URI para consultar disponibilidade do domínio. Ainda é possível percorrer a coleção domínios para descobrir o que o URI de um determinado domínio é, mas dado o imenso número de domínios que gere, este não seria viável para o cliente, assim dando-lhes uma maneira de adivinhar o que o URI de um recurso do domínio pode ser é uma grande vitória em termos de facilidade de implementação a partir da perspectiva do cliente, e largura de banda do servidor do.
Por à sua pergunta:. Nossa documentação normativa é recursos expostas, o efeito de vários métodos sobre esses recursos e os tipos de mídia de representação utilizados e seus esquemas, e que tipo de recursos os URIs nesses representions apontar para
Nós também incluímos não-normativa documentação (informativo) que seja acompanhada de um aviso para não ler muito para os URIs mencionados no documento, que dá exemplos de interações típicas cliente-servidor. Isso coloca a documentação normativa bastante abstrato em termos concretos.
Eu penso sobre o número de anos que o descanso foi para fora lá agora, tecnólogos chegaram a um acordo com o conceito de um recurso eo que realmente é ou não RESTful.
De acordo com a Maturidade Richardson Modelo, existem 4 níveis (0-3) que definem como RESTful sua API é, com 3 significando uma API RESTful verdadeiramente, assim como Roy Fielding pretendia que fosse.
Nível 0 é quando você tem um ponto de entrada URI -. Como o sabão
Nível 1 significa que a API é capaz de distinguir entre diferentes recursos, e tem mais de pontos de entrada -. Ainda tem cheiro de sabão
Nível 2 é quando você usa HTTP verbos - GET, POST, DELETE principalmente. Este é o nível em que RESTO realmente vem em imagem.
No nível 3, você começar a usar controles de hipermídia para tornar a sua API realmente RESTful.
Links sugeridos para leitura:
Vamos supor GET /foos/createForm é invocado para obter valores de campos de formulário para o qual devem ser fornecidos quando vamos para criar POST /foos. Agora, este URL especial ou seja a 1 usada para criar foos deve ser mencionado na resposta para GET /foos/createForm como um elo ação de envio de acordo com a proposição de Fielding, certo?
Então, qual é o benefício de ações de mapeamento para o bem-conhecido Http verbos para ações, "Convenção sobre o código / config" coisa é anulada.
