Was ist die Notwendigkeit für 'Erkennbarkeit' in einer REST-API, wenn die Clients nicht weit genug fortgeschritten sind, um diese überhaupt zu nutzen?

Die verschiedenen Vorträge und Tutorials, die ich auf REST gescannt habe, scheinen etwas zu betonen, das als "Entdeckbarkeit" bezeichnet wird. Nach meinem begrenzten Verständnis scheint der Begriff zu bedeuten, dass ein Kunde in der Lage sein sollte http://URL, eine Liste der möglichen Aktivitäten abzurufen.

Was ich nur schwer verstehe, ist, dass "Software-Clients" keine Menschen sind. Es handelt sich lediglich um Programme, die nicht über das intuitive Wissen verfügen, um genau zu verstehen, was mit den bereitgestellten Links geschehen soll. Nur Menschen können auf eine Website gehen und den dargestellten Text und die angezeigten Links verstehen und darauf reagieren.

Was ist der Punkt der Auffindbarkeit, wenn der Client-Code, der auf solche auffindbaren URLs zugreift, tatsächlich nichts damit anfangen kann, es sei denn, der menschliche Entwickler des Clients experimentiert tatsächlich mit den präsentierten Ressourcen? Dies sieht genauso aus wie die Definition der verfügbaren Funktionen in einem Dokumentationshandbuch, nur aus einer anderen Perspektive und mit einem höheren Arbeitsaufwand für den Entwickler. Warum wird dieser zweite Ansatz der Vordefinition, was in einem Dokument außerhalb der tatsächlichen REST-Ressourcen getan werden kann, als minderwertig betrachtet?

Das Erfordernis der Auffindbarkeit ist möglicherweise nicht relevant, aber die Links, die die Auffindbarkeit ermöglichen, dienen mehr Zwecken. Das wichtigste davon ist meines Erachtens, dass das Bereitstellen vollständiger URIs in den Antworten an den Client bedeutet, dass kein Client jemals einen URI "komponieren" muss. Das bedeutet, dass kein Kunde jemals Kenntnisse darüber benötigen wird, wie die URIs aufgebaut sind. Dies wiederum ermöglicht es den Serverentwicklern, das URI-Schema zu ändern, wann immer es für sie geeignet ist, da ältere Clients, die sich noch auf eine alte Art der Strukturierung von URIs verlassen, nicht berücksichtigt werden müssen.

"Clients" sind möglicherweise nicht weit genug fortgeschritten, um davon Gebrauch zu machen, aber die Benutzer von Clients können dies. Ein Client kann schließlich so einfach wie ein Webbrowser sein. Bei der Auffindbarkeit geht es darum, den Benutzern das Erlernen und Verwenden der API zu ermöglichen .

Zum Beispiel hat Jenkins (der CI-Server) eine REST-ähnliche Schnittstelle. Gehen Sie zu einer beliebigen Seite, geben Sie die URL mit "/ api" ein, und Sie erhalten eine Seite, die alles beschreibt, was Sie tun können. Es macht das Lernen der API trivial. Mit http://ci.jruby.org gelangen Sie beispielsweise zum jenkins-Server für jruby und mit http://ci.jruby.org/api zum API für diese bestimmte Seite.

Ich hatte vor einiger Zeit das Vergnügen, mit einer API zu arbeiten, deren Dokumentation sehr, sehr schwer zu verstehen war.

Nachdem ich eine tatsächliche Antwort vom Server erhalten hatte, war es möglich, die Dokumentation mit der Serverantwort zu vergleichen und diese zum Entschlüsseln der Dokumentation zu verwenden (und ja, es war der richtige Begriff zu entschlüsseln). Das Problem bestand darin, dass, wenn eine Anfrage an den Server gesendet wurde, die der Spezifikation nicht genau entsprach, nur eine Fehlermeldung ausgegeben wurde. Aufgrund der unlesbaren Dokumentation war es nahezu unmöglich, herauszufinden, wie die richtigen Anfragen gesendet werden sollten. Es gab auch verschiedene Versionen der API-Dokumentation, die nicht miteinander übereinstimmten und wahrscheinlich nicht mit der API selbst übereinstimmten. das hat nicht geholfen.

Wenn es einen Befehl gegeben hätte, den ich an den Server senden könnte, eine Liste aller möglichen Befehle und wie genau sie gesendet werden sollen, wäre das äußerst hilfreich gewesen. Die Auffindbarkeit ist nicht nur für Kunden, sondern auch für Softwareentwickler nützlich.

ANMERKUNG: Ich bin kein Experte in diesem Thema, aber ich habe einen ähnlichen Prozess durchlaufen, bei dem ich versucht habe, die verschiedenen Nuancen der Interpretationen von "REST" vor einigen Jahren miteinander in Einklang zu bringen Zeit.

Meines Erachtens stammt dies aus Roy Fieldings Hypermedia als Engine of Application State, auch bekannt als "HATEOAS", das dann die Idee eines "semantischen Webs" ermöglicht.

Also ... im Grunde genommen und, wie ich es verstehe, machen Sie Ihre RESTful-Anwendung im Grunde selbstbeschreibend, so dass der Verbraucher keine Vorkenntnisse über einen formellen Vertrag haben muss, um Ihre Inhalte / Funktionen zu nutzen. Sie können von einem bestimmten Standard-Root-Endpunkt aus eine Verbindung herstellen und dann kontextrelevante Links aufrufen, die Ihre App bereitstellt, wenn der Verbraucher interagiert. Der Verbraucher kann natürlich eine Person oder ein systemischer Agent sein.

Wenn Sie "REST" nur für hübsche URLs verwenden, die CRUD-Vorgängen zugeordnet sind, über die ein Verbraucher nach einem bekannten Vertrag im Voraus Bescheid wissen und anrufen muss, würde Roy Fielding dies als nicht wirklich REST-konform erachten.

Das heißt nicht, dass ein RPC-Service mit REST-Aroma nicht nützlich sein kann / eine Verbesserung gegenüber einem aufwändigeren RPC-Modell, das für eine eingeschränkte / kontrollierte Nutzung geeignet ist, aber die Hardliner werden ihre Nasen runterblicken und es als degeneriert betrachten Ich bin nicht wirklich REST.