Est-ce REST API vraiment RPC? Roy Fielding semble penser ainsi
Une grande partie de ce que je pensais savoir sur REST est apparemment faux - et je ne suis pas seul. Cette question a une longue introduction, mais elle semble nécessaire parce que les informations sont un peu dispersé. La vraie question vient à la fin si vous êtes déjà familier avec ce sujet.
D'après le premier paragraphe de Roy Fielding les API REST doivent être basées sur l'hypertexte , il est assez clair qu'il pense que son travail est largement mal interprété:
Je suis frustré par le nombre de personnes appelant une interface basée sur HTTP une API REST. L'exemple d'aujourd'hui est le SocialSite REST) =. C'est du RPC. Ça crie du RPC. Il y a tellement de couplage sur l'affichage qu'il faut lui donner une cote X.
Fielding continue de répertorier plusieurs attributs d'une API REST. Certains d'entre eux semblent aller à la fois contre la pratique courante et les conseils communs sur SO et d'autres forums. Pour exemple:
Une API REST doit être saisie sans connaissance préalable au-delà de l'URI initial (signet) et d'un ensemble de types de supports standardisés qui conviennent au public cible (c'est-à-dire, qui devrait être compris par tout client qui peut utiliser l'API). ...
A REST ne doit pas définir de noms ou de hiérarchies de ressources fixes (un couplage évident de client et de serveur). ...
Une API REST doit consacrer presque tout son effort descriptif à définir le ou les types de support utilisés pour représenter les ressources et piloter l'état de l'application, ou pour définir des noms de relation étendus et/ou une marque activée par hypertexte -up pour les types de supports standard existants. ...
L'idée d '"hypertexte" joue un rôle central - beaucoup plus que la structure URI ou ce que signifient les verbes HTTP. "Hypertexte" est défini dans l'un des commentaires:
Quand je [Fielding] dis hypertexte, je veux dire la présentation simultanée d'informations et de contrôles de telle sorte que les informations deviennent le moyen par lequel l'utilisateur (ou l'automate) obtient des choix et sélectionne des actions. Hypermédia n'est qu'une extension de ce que signifie le texte pour inclure des ancres temporelles dans un flux multimédia; la plupart des chercheurs ont abandonné la distinction.
L'hypertexte n'a pas besoin d'être HTML sur un navigateur. Les machines peuvent suivre des liens lorsqu'elles comprennent le format de données et les types de relations.
J'imagine à ce stade, mais les deux premiers points ci-dessus semblent suggérer que la documentation API pour une ressource Foo qui ressemble à ce qui suit conduit à un couplage étroit entre le client et le serveur et n'a pas sa place dans un système RESTful.
GET /foos/{id} # read a Foo
POST /foos/{id} # create a Foo
PUT /foos/{id} # update a Foo
Au lieu de cela, un agent devrait être forcé de découvrir les URI de tous les Foos en émettant, par exemple, une demande GET contre/foos. (Ces URI peuvent s'avérer suivre le modèle ci-dessus, mais ce n'est pas la question.) La réponse utilise un type de support capable de transmettre comment accéder à chaque élément et ce qui peut être fait avec, donnant lieu au troisième point ci-dessus . Pour cette raison, la documentation de l'API doit se concentrer sur l'explication de l'interprétation de l'hypertexte contenu dans la réponse.
De plus, chaque fois qu'un URI à une ressource Foo est demandé, la réponse contient toutes les informations nécessaires à un agent pour découvrir comment procéder en, par exemple, en accédant aux ressources associées et parentales via leurs URI, ou en prenant des mesures après la création/suppression d'une ressource.
La clé de tout le système est que la réponse consiste en un hypertexte contenu dans un type de média qui lui-même transmet aux options d'agent pour continuer. Ce n'est pas différent de la façon dont un navigateur fonctionne pour les humains.
Mais c'est juste ma meilleure estimation à ce moment particulier.
Fielding a publié un suivi dans lequel il a répondu aux critiques selon lesquelles sa discussion était trop abstraite, manquant d'exemples et riche en jargon:
D'autres essaieront de déchiffrer ce que j'ai écrit de manière plus directe ou applicable à certaines préoccupations pratiques d'aujourd'hui. Je ne le ferai probablement pas, parce que je suis trop occupé à me débattre avec le sujet suivant, à préparer une conférence, à rédiger une autre norme, à voyager dans un endroit éloigné ou à faire les petites choses qui me font sentir que j'ai gagné mon chèque de paie.
Donc, deux questions simples pour les experts REST là-bas avec un état d'esprit pratique: comment interprétez-vous ce que Fielding dit et comment le mettez-vous en pratique lors de la documentation/mise en œuvre REST API?
Edit: cette question est un exemple de la difficulté d'apprendre quelque chose si vous n'avez pas de nom pour ce dont vous parlez. Le nom dans ce cas est "Hypermedia comme moteur de l'état de l'application" (HATEOAS).
Je pense que votre explication le couvre principalement. Les URI sont des identifiants opaques qui ne doivent pas, pour la plupart, être communiqués au-delà de l'URI du signet utilisé par l'agent utilisateur pour accéder à l'application.
Quant à la documentation, cette question a été posée plusieurs fois. Vous documentez votre type de média, ainsi que les contrôles hyperliens qu'il contient (liens et formulaires), et le modèle d'interaction si vous le souhaitez (voir AtomPub).
Si vous documentez les URI ou comment les construire, vous vous trompez.
Votre interprétation me semble correcte. Je crois que les contraintes de Fielding peuvent être appliquées pratiquement.
J'aimerais vraiment que quelqu'un publie de bons exemples sur la façon de documenter une interface REST. Il y a tellement de mauvais exemples, en avoir des valides pour pointer les utilisateurs serait très précieux.
Je cherchais un bon exemple d'une API écrite à la suite de HATEOAS et j'ai eu du mal à en trouver une (j'ai trouvé les API SunCloud et AtomPub difficiles à appliquer à une situation d'API "normale"). J'ai donc essayé de faire un exemple réaliste sur mon blog qui a suivi les conseils de Roy Fieldings sur ce que signifie être une bonne implémentation REST. J'ai trouvé très difficile de donner l'exemple, malgré le fait que c'est assez simple en principe (juste confus lorsque l'on travaille avec une API par opposition à une page Web). Je comprends ce que Roy contestait et je suis d'accord, c'est juste un changement de mentalité à mettre en œuvre correctement pour une API.
Jetez un œil: Exemple d'API utilisant Rest
La chose que la plupart des gens se trompent est que (du moins je pense) dans le monde REST) vous ne documentez pas votre "interface de repos", ce que vous documentez est un type de média, indépendamment de votre serveur ou service.
Pour ceux qui sont intéressés, j'ai trouvé un exemple détaillé de HATEOAS en pratique dans le Sun Cloud API .
La seule exception à donner des instructions sur la façon de créer des URI est qu'il est permis d'envoyer un modèle d'URI dans la réponse hypertexte, avec des champs à remplacer automatiquement par le client, en utilisant d'autres champs dans l'hypertexte. Cela ne finit généralement pas par économiser beaucoup de bande passante, car la compression gzip gérera suffisamment les parties répétées des URI pour ne pas se soucier de cela.
Quelques bonnes discussions sur REST et les HATEOAS associés:
Avantages de (également) l'utilisation de HATEOAS dans les API RESTFul
Je pense qu'au fil des années que REST a été là-bas maintenant, les technologues ont accepté le concept d'une ressource et ce qui est vraiment ou non RESTful.
Selon le modèle de maturité Richardson, il existe 4 niveaux (0-3) qui définissent le degré de RESTful de votre API, 3 signifiant une véritable API RESTful, tout comme Roy Fielding le voulait.
Le niveau 0 est lorsque vous avez un point d'entrée UAP de type URI.
Le niveau 1 signifie que l'API est capable de faire la distinction entre différentes ressources et possède plus d'un point d'entrée - qui sent toujours le SOAP.
Le niveau 2 est lorsque vous utilisez des verbes HTTP - GET, POST, DELETE principalement. C'est le niveau auquel REST entre vraiment en image.
Au niveau 3, vous commencez à utiliser des contrôles hypermédia pour rendre votre API vraiment RESTful.
Liens suggérés pour une lecture plus approfondie:
Absolument correct. Je noterais en outre que les modèles d'URI sont parfaitement adaptés à une application RESTful tant que les modèles proviennent de documents reçus du serveur (OpenSearch en est un exemple approprié). Pour les modèles d'URI, vous documentez où ils sont utilisés et quels sont les espaces réservés attendus dans le modèle, mais pas les modèles eux-mêmes. Un peu contrairement à ce que Wahnfrieden a dit, ce n'est pas une exception.
Par exemple, dans mon travail, nous avons un système de gestion de domaine interne, et le document de service spécifie deux modèles d'URI: un pour produire un URI de meilleure estimation pour une ressource de domaine, et un autre pour construire un URI pour interroger la disponibilité du domaine. Il est toujours possible de parcourir la collection de domaines pour déterminer l'URI d'un domaine donné, mais étant donné le nombre immense de domaines qu'il gère, cela ne serait pas faisable pour le client, leur donnant ainsi un moyen de deviner ce que le L'URI d'une ressource de domaine pourrait être une énorme victoire en termes de facilité de mise en œuvre du point de vue du client et de bande passante du serveur.
Sur votre question: Notre documentation normative est les ressources exposées, l'effet de diverses méthodes sur ces ressources, les types de supports de représentation utilisés et leurs schémas, et le type de ressources vers lesquelles les URI dans ces représentations pointent.
Nous incluons également une documentation non normative (informative) à laquelle est jointe une clause de non-responsabilité de ne pas trop lire dans les URI mentionnés dans le document, qui donne des exemples d'interactions client-serveur typiques. Cela met la documentation normative plutôt abstraite en termes concrets.
Assumons GET /foos/createForm est invoqué pour obtenir les valeurs des champs de formulaire qui doivent être fournies lorsque nous allons créer POST /foos. Maintenant, cette URL particulière, c'est-à-dire le 1 utilisé pour créer des foos, doit être mentionnée dans la réponse pour GET /foos/createForm en tant que lien d'action de soumission conformément à la proposition de Fielding, n'est-ce pas?
.