Est-ce que l'API REST vraiment RPC? Roy Fielding semble le penser

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

  •  18-09-2019
  •  | 
  •  

Question

Une grande quantité de ce que je pensais que je connaissais REST est apparemment mal - et je ne suis pas seul. Cette question a une longue plomb, mais il semble être nécessaire parce que l'information est un peu dispersée. La question réelle est à la fin si vous êtes déjà familier avec ce sujet.

Dès le premier paragraphe de API REST must Roy Fielding être axée sur l'hypertexte, il est assez clair qu'il croit que son travail est largement mal interprété:

  

Je suis frustré par le se nombre de personnes appelant une interface HTTP d'une API REST. L'exemple d'aujourd'hui est le SocialSite API REST . C'est RPC. Il crie RPC. Il y a tellement de couplage sur l'écran qu'il doit donner une cote X.

Fielding se poursuit à la liste de plusieurs attributs d'une API REST. Certains d'entre eux semblent aller à l'encontre à la fois pratique courante et des conseils communs sur les forums et autres SO. Par exemple:

  • Une API REST doit être entré sans connaissance préalable au-delà de l'URI initial (marque-page) et un ensemble de types de supports standardisés qui sont appropriés pour le public visé (c.-à-devrait être compris par tout client qui pourrait utiliser le API). ...

  • Une API REST ne doit pas définir les noms de ressources fixes ou des hiérarchies (un couplage évident du client et le serveur). ...

  • Une API REST devrait passer la quasi-totalité de ses efforts descriptif dans la définition du type de support (s) utilisé pour représenter des ressources et de l'état d'application de conduite, ou dans la définition des noms de relation étendue et / ou majoration de l'hypertexte activé existants types de support standard. ...

L'idée de « hypertexte » joue un rôle central - beaucoup plus que la structure URI ou ce que les verbes HTTP signifient. « Hypertext » est défini dans l'un des commentaires:

  

Quand je [Fielding] dire hypertexte, je veux dire la présentation simultanée de l'information et des contrôles tels que les informations devient le affordance par lequel l'utilisateur (ou automate) obtient des choix et des actions sélectionne. Hypermédia est juste une extension de ce texte signifie pour inclure des ancres temporelles dans un flux multimédia; la plupart des chercheurs ont abandonné la distinction.

     

Hypertext n'a pas besoin d'être HTML sur un navigateur. Les machines peuvent suivre les liens quand ils comprennent le format de données et types relationnels.

Je devine à ce stade, mais les deux premiers points ci-dessus semblent suggérer que la documentation de l'API pour une ressource Foo qui ressemble les pistes suivantes à 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 doit être forcé de découvrir les URIs pour tous Foos, par exemple, l'émission d'une requête GET contre / foos. (Ces URIs peuvent se révéler suivre le modèle ci-dessus, mais c'est à côté du point.) La réponse utilise un type de support qui est capable de transmettre comment accéder à chaque article et ce qui peut être fait avec elle, donnant lieu au troisième point ci-dessus . Pour cette raison, la documentation de l'API devrait se concentrer sur l'explication de la façon d'interpréter l'hypertexte contenu dans la réponse.

En outre, chaque fois qu'un URI à une ressource Foo est demandée, la réponse contient toutes les informations nécessaires à un agent de découvrir comment procéder, par exemple, l'accès aux ressources associées et des parents par leurs URIs, ou en prenant des mesures après la création / suppression d'une ressource.

La clé de l'ensemble du système est que la réponse se compose d'hypertexte contenu dans un type de support qui se transmet aux options de l'agent pour l'instance. Il est semblable à la façon dont un navigateur fonctionne pour l'homme.

Mais ce n'est ma meilleure estimation à ce moment précis.

Fielding a affiché un

Était-ce utile?

La solution

Je pense que votre explication couvre la plupart du temps il. URIs sont des identifiants opaques au-delà de l'URI marque devrait, pour la plupart, pas communiquaient qui est utilisé par l'agent utilisateur pour accéder à l'application.

En ce qui concerne la documentation, cette question a été fait à quelques reprises. Vous documentez votre type de support, ainsi que le lien hypertexte contrôle qu'il contient (liens et formulaires), et le modèle d'interaction si vous le souhaitez (voir AtomPub).

Si vous documentez les URIs ou comment les construire, vous le faites mal.

Autres conseils

Votre interprétation me semble correct. Je crois que les contraintes de Fielding peuvent être appliquées dans la pratique.

Je voudrais vraiment voir quelqu'un publier quelques bons exemples de la façon de documenter une interface REST. Il y a tellement de mauvais exemples, ont quelques ceux valables pour diriger les utilisateurs vers serait très utile.

La seule exception à donner des instructions sur la façon de construire des URI est qu'il est permis d'envoyer un modèle URI dans la réponse de l'hypertexte, avec des champs à substituer automatiquement par le client, à l'aide d'autres champs dans l'hypertexte. Cela ne veut pas finir par faire gagner beaucoup de bande passante, bien que depuis la compression gzip traitera les parties répétées de URIs assez bien pour ne pas se soucier de cela.

Quelques bonnes discussions sur REST et les HATEOAS connexes:

avantages de (aussi) L'utilisation HATEOAS Dans API RESTFul

Comment obtenir une tasse de café

Pour les intéressés, je trouve un exemple détaillé de HATEOAS dans la pratique dans l'API Sun Nuage .

La seule chose que la plupart des gens mal est que (je pense au moins) dans le monde REST vous ne documentent pas votre « Interface Rest », ce que vous document est un type de média, indépendamment de votre serveur ou d'un service.

Tout à fait correct. Je constate en outre que les modèles que les URI sont parfaitement bien dans une application RESTful tant que les modèles sont des documents reçus du serveur (OpenSearch étant un exemple approprié). Pour les modèles d'URI, vous document dans lequel ils sont utilisés et ce que les espaces réservés attendus dans le modèle sont, mais pas les modèles eux-mêmes. Légèrement contrairement à ce que dit Wahnfrieden, ce n'est pas une exception.

Par exemple, dans mon travail que nous avons un système interne de gestion de domaine, et le document de service spécifie deux modèles URI: un pour produire une meilleure estimation URI pour une ressource de domaine, et un autre pour la construction d'un URI pour effectuer des requêtes disponibilité de domaine. Il est toujours possible de parcourir la collection de domaines pour comprendre ce que l'URI d'un domaine donné est, mais étant donné le nombre immense de domaines qu'elle gère, ce ne serait pas possible pour le client, afin de leur donner un moyen de deviner ce que URI d'une ressource de domaine pourrait être une grande victoire en termes de facilité de mise en œuvre du point de vue du client, et la bande passante

à partir du serveur.

à votre question: Nos ressources est exposée la documentation normative, l'effet de diverses méthodes sur ces ressources, et les types de médias de représentation utilisés et leurs schémas, et quel genre de ressources les URIs dans ces representions pointent vers

Nous incluons aussi la documentation non-normative (informative) qui a attaché à un avertissement de ne pas lire trop dans les URIs mentionnés dans le document, ce qui donne des exemples d'interactions typiques client-serveur. Cela met la documentation normative plutôt abstraite en termes concrets.

Je pense que sur le nombre d'années que le repos a été là-bas maintenant, les techniciens sont venus à accepter le concept d'une ressource et ce qui est vraiment ou n'est pas RESTful.

Selon le modèle de maturité Richardson, il y a 4 niveaux (0-3) qui définissent la façon dont votre RESTful API est, avec 3 sens une API RESTful vraiment, tout comme Roy Fielding voulait qu'il soit.

Niveau 0 est quand vous avez un URI point d'entrée -. Comme SOAP

Niveau 1 signifie que l'API est capable de faire la distinction entre les différentes ressources, et a plus d'un des points d'entrée -. Sent encore SOAP

Le niveau 2 est lorsque vous utilisez les verbes HTTP - GET, POST, SUPPRIMER principalement. Ceci est le niveau auquel REST est vraiment dans l'image.

Au niveau 3, vous commencez à utiliser les contrôles hypermédia pour rendre votre API vraiment RESTful.

Liens suggérés pour en savoir plus:

Supposons GET /foos/createForm est invoquée pour obtenir des champs de formulaire pour les valeurs qui doivent être fournies lorsque nous allons créer POST /foos. Maintenant, cette URL particulière i.e. le 1 utilisé pour créer foos doit être mentionné dans la réponse pour GET /foos/createForm comme lien d'action présenter selon la proposition de Fielding, non?
   Alors quel est l'avantage des actions de cartographie à bien connus des verbes Http aux actions, « convention sur le code / config » chose est réduit à néant.

Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top