Quel est le besoin de «découverte» dans une API REST lorsque les clients ne sont pas assez avancés pour l'utiliser de toute façon?

Les différents exposés que j'ai regardés et les didacticiels que j'ai scannés sur REST semblent mettre l'accent sur quelque chose appelé «découvrabilité». À ma connaissance limitée, le terme semble signifier qu'un client devrait pouvoir aller http://URL- et obtenir automatiquement une liste de choses qu'il peut faire.

Ce que j'ai du mal à comprendre, c'est que les «clients logiciels» ne sont pas des êtres humains. Ce ne sont que des programmes qui n'ont pas les connaissances intuitives pour comprendre quoi faire exactement avec les liens fournis. Seules les personnes peuvent accéder à un site Web et donner un sens au texte et aux liens présentés et agir en conséquence.

Quel est donc l'intérêt de la possibilité de découverte, lorsque le code client qui accède à de telles URL détectables ne peut réellement rien en faire, à moins que le développeur humain du client n'effectue réellement des expériences avec les ressources présentées? Cela ressemble exactement à la définition de l'ensemble des fonctions disponibles dans un manuel de documentation, venant d'une direction différente et impliquant en fait plus de travail pour le développeur. Pourquoi cette seconde approche consistant à prédéfinir ce qui peut être fait dans un document externe aux ressources REST réelles, est-elle considérée comme inférieure?

Le besoin de découvrabilité n'est peut-être pas pertinent, mais les liens qui permettent la découvrabilité servent à d'autres fins. Le plus important d'entre eux, à mon avis, est que le fait de fournir des URI complets dans les réponses au client signifie qu'aucun client n'aura jamais besoin de «composer» un URI. Cela signifie qu'aucun client n'aura jamais besoin de savoir comment les URI sont structurés. Et cela permet aux développeurs de serveurs de changer le schéma d'URI quand cela leur convient car ils n'ont pas besoin de considérer que les clients plus âgés s'appuient toujours sur une ancienne façon de structurer les URI.

Les "clients" ne sont peut-être pas suffisamment avancés pour en faire usage, mais les utilisateurs des clients le peuvent. Un client peut être quelque chose d'aussi simple qu'un navigateur Web, après tout. La découvrabilité consiste à permettre aux gens d'apprendre et d'utiliser l'API .

Par exemple, Jenkins (le serveur CI) a une interface de type REST. Allez sur n'importe quelle page, fixez l'URL avec "/ api", et vous obtenez une page décrivant tout ce que vous pouvez faire. Cela rend l'apprentissage de l'API trivial. Par exemple, http://ci.jruby.org vous amène au serveur jenkins pour jruby et http://ci.jruby.org/api vous amène à l'API pour cette page spécifique.

J'ai eu le plaisir, il y a quelque temps, de travailler avec une API contenant une documentation très, très difficile à comprendre.

Une fois que j'ai réussi à obtenir une réponse réelle du serveur, il a été possible de comparer la documentation avec la réponse du serveur et de l'utiliser pour déchiffrer la documentation (et oui, la déchiffrer était le bon terme). Le problème était que si une demande était envoyée au serveur qui n'était pas exactement correcte selon la spécification, vous obtiendriez simplement une erreur, et avec la documentation illisible, trouver comment envoyer les demandes correctes était presque impossible. Il y avait aussi différentes versions de la documentation de l'API qui n'étaient pas d'accord entre elles et probablement pas d'accord avec l'API elle-même; cela n'a pas aidé.

S'il y avait eu une commande que je pouvais envoyer au serveur, renvoyant une liste de toutes les commandes possibles et comment les envoyer exactement, cela aurait été extrêmement utile. La découvrabilité n'est pas seulement pour les clients, elle est également utile pour les développeurs de logiciels.

REMARQUE: Je ne suis pas un expert en la matière, mais j'ai suivi un processus similaire pour essayer de concilier les différentes nuances des interprétations des gens de «REST» il y a quelques années, et c'est la leçon à retenir que j'ai tirée de mon examen de la temps.

À ma connaissance, cela découle de l' hypermédia de Roy Fielding en tant que moteur d'état de l'application, alias "HATEOAS", qui devient alors un catalyseur de l'idée d'un "Web sémantique".

Donc ... fondamentalement, et encore une fois, si je comprends bien, vous faites votre application RESTful essentiellement auto-décrivant de telle sorte que le consommateur n'a pas besoin d'avoir une connaissance préalable d'un contrat formel pour consommer votre contenu / fonctionnalité. Ils peuvent s'engager à partir d'un point de terminaison racine par défaut, puis parcourir des liens contextuellement pertinents que votre application fournit lorsque le consommateur interagit. Le consommateur, bien sûr, peut être une personne ou un agent systémique.

Si vous utilisez simplement "REST" pour de jolies URL mappées à des opérations CRUD qu'un consommateur doit avoir une connaissance préalable et appelle selon un contrat bien connu, Roy Fielding ne le jugerait pas vraiment RESTful.

Cela ne veut pas dire qu'un service RPC à saveur REST ne peut pas être utile / une amélioration par rapport à un modèle RPC plus élaboré et adapté à une utilisation limitée / contrôlée, mais les extrémistes le regarderont de haut et le considéreront comme dégénéré. / pas vraiment REPOS.