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 car les informations sont un peu dispersées. La vraie question vient à la fin si vous êtes déjà familier avec ce sujet.
Depuis le premier paragraphe des API REST de Roy Fielding 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 qui appellent une interface HTTP une API REST. L'exemple d'aujourd'hui est l' API REST SocialSite . C'est RPC. Il crie RPC. Il y a tellement de couplage à l'écran qu'il devrait recevoir une note X.
Fielding poursuit en répertoriant plusieurs attributs d'une API REST. Certains d'entre eux semblent aller à l'encontre à la fois de la pratique courante et des conseils communs sur les SO et d'autres forums. Par exemple:
Une API REST doit être saisie sans aucune connaissance préalable au-delà de l'URI initial (signet) et de l'ensemble de types de supports standardisés qui sont appropriés pour le public visé (c'est-à-dire, censés être compris par tout client qui pourrait utiliser l'API). ...
Une API REST ne doit pas définir de noms ou de hiérarchies de ressources fixes (un couplage évident du client et du serveur). ...
Une API REST doit consacrer presque tout son effort de description à la définition du ou des types de médias utilisés pour représenter les ressources et à la gestion de l'état de l'application, ou à la définition de noms de relations étendus 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 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 sorte que l'information devienne le moyen par lequel l'utilisateur (ou l'automate) obtient des choix et sélectionne des actions. Hypermedia est juste 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 ordinateurs peuvent suivre les liens lorsqu'ils comprennent le format des 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 pour tous les Foos, par exemple en émettant une requête 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 média capable de transmettre comment accéder à chaque élément et ce qui peut être fait avec, ce qui donne lieu au troisième point ci-dessus . Pour cette raison, la documentation de l'API doit se concentrer sur l'explication de la manière d'interpréter l'hypertexte contenu dans la réponse.
De plus, chaque fois qu'un URI vers une ressource Foo est demandé, la réponse contient toutes les informations nécessaires à un agent pour découvrir 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 lui-même transmet à l'agent des options pour continuer. Ce n'est pas sans rappeler la façon dont un navigateur fonctionne pour les humains.
Mais ce n'est que ma meilleure estimation à ce moment précis.
Fielding a publié un suivi dans lequel il a répondu aux critiques selon lesquelles sa discussion était trop abstraite, manquait d'exemples et riche en jargon:
D'autres essaieront de déchiffrer ce que j'ai écrit de manière plus directe ou applicable à une préoccupation pratique d'aujourd'hui. Je ne le ferai probablement pas, car je suis trop occupé à m'attaquer au sujet suivant, à préparer une conférence, à écrire un autre standard, à voyager dans un endroit éloigné ou à faire simplement les petites choses qui me donnent l'impression d'avoir gagné mon chèque de paie.
Donc, deux questions simples pour les experts REST avec un état d'esprit pratique: comment interprétez-vous ce que dit Fielding et comment le mettez-vous en pratique lors de la documentation / mise en œuvre 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 comme moteur de l'état d'application" (HATEOAS).