Une grande partie de ce que je pensais savoir sur REST est apparemment erronée - et je ne suis pas le seul. Cette question a une longue introduction, mais elle semble nécessaire car les informations sont un peu éparpillées. La question proprement dite vient à la fin si vous êtes déjà familiarisé avec ce sujet.
Dès le premier paragraphe de l'ouvrage de Roy Fielding Les API REST doivent être axées sur l'hypertexte. il est clair qu'il pense que son travail est largement mal interprété :
Je suis de plus en plus frustré par le nombre de personnes qui appellent toute interface basée sur le protocole HTTP une API REST. L'exemple d'aujourd'hui est l SocialSite REST API . C'est RPC. Ça crie RPC. Il y a tellement d'accouplement sur l'étalage qu'on devrait lui donner une cote X.
Fielding poursuit en énumérant plusieurs attributs d'une API REST. Certains d'entre eux semblent aller à l'encontre des pratiques et des conseils courants sur SO et d'autres forums. Par exemple :
-
On doit pouvoir accéder à une API REST sans autre connaissance préalable que l'URI (signet) initial et l'ensemble des types de médias normalisés qui conviennent au public visé (c'est-à-dire qui devraient être compris par tout client susceptible d'utiliser l'API). ...
-
Une API REST ne doit pas définir de noms ou de hiérarchies de ressources fixes (un couplage évident entre le client et le serveur). ...
-
Une API REST doit consacrer la quasi-totalité de ses efforts descriptifs à la définition du ou des types de médias utilisés pour représenter les ressources et piloter l'état de l'application, ou à la définition de noms de relations étendues et/ou de balisage hypertexte pour les types de médias standard existants. ...
L'idée d'"hypertexte" joue un rôle central, bien plus que la structure des URI ou la signification des verbes HTTP. "Hypertexte" est défini dans l'un des commentaires :
Lorsque je [Fielding] parle d'hypertexte, j'entends la présentation simultanée d'informations et de contrôles, de telle sorte que les informations deviennent l'instrument par lequel l'utilisateur (ou l'automate) obtient des choix et sélectionne des actions. L'hypermédia n'est qu'une expansion de ce que signifie le texte pour inclure des ancrages temporels dans un flux médiatique ; la plupart des chercheurs ont abandonné la distinction.
L'hypertexte ne doit pas nécessairement être du HTML sur un navigateur. Les machines peuvent suivre les liens lorsqu'elles comprennent le format des données et les types de relations.
Je ne fais que supposer à 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 FooAu lieu de cela, un agent devrait être obligé de découvrir les URI de tous les Foos en émettant, par exemple, une requête GET sur /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 média capable d'indiquer comment accéder à chaque élément et ce qui peut en être fait, ce qui donne lieu au troisième point ci-dessus. C'est pourquoi la documentation de l'API doit s'attacher à expliquer comment interpréter l'hypertexte contenu dans la réponse.
En outre, chaque fois qu'une URI vers une ressource Foo est demandée, la réponse contient toutes les informations nécessaires pour qu'un agent découvre comment procéder, par exemple en accédant aux ressources associées et parentes 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 transmet lui-même à l'agent des options pour poursuivre. Cela n'est pas sans rappeler le fonctionnement d'un navigateur pour les humains.
Mais c'est juste ma meilleure supposition à ce moment précis.
Fielding a affiché un suivi dans lequel il répondait aux critiques selon lesquelles son exposé était trop abstrait, manquait d'exemples et était riche en jargon :
D'autres essaieront de déchiffrer ce que j'ai écrit de manière plus directe ou plus applicable à une préoccupation pratique d'aujourd'hui. Je ne le ferai probablement pas, car je suis trop occupé à traiter le prochain sujet, à préparer une conférence, à rédiger une autre norme, à voyager dans un pays lointain ou à faire les petites choses qui me donnent le sentiment d'avoir mérité mon salaire.
J'ai donc deux questions simples à poser aux experts REST ayant un esprit pratique : comment interprétez-vous les propos de M. Fielding et comment les mettez-vous en pratique lorsque vous documentez/implémentez des API REST ?
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 as the Engine of Application State" (HATEOAS).
