Ist das REST API wirklich RPC? Roy Fielding scheint so zu denken

https://stackoverflow.com/questions/1164154

rest
hateoas

18-09-2019
|

Frage

Eine große Menge von dem, was ich dachte, dass ich über REST wusste offenbar falsch - und ich bin nicht allein. Diese Frage hat einen langen Vorlauf in, aber es scheint notwendig zu sein, weil die Informationen ein wenig zerstreut. Die eigentliche Frage am Ende kommt, wenn Sie sich mit diesem Thema bereits vertraut sind.

Aus dem ersten Absatz von Roy Fieldings REST APIs Muss sein Hypertext-driven , es ist ziemlich klar, dass er glaubt, dass seine Arbeit weitgehend falsch interpretiert wird:

Ich erhalte durch die Anzahl der Menschen rufen jede HTTP-basierte Schnittstelle eines REST-API frustriert. Das heutige Beispiel ist die SocialSite REST API . Das ist RPC. Es schreit RPC. Es gibt so viel Kopplung auf dem Display, dass es eine X-Rating gegeben werden sollte.

Fieldings geht auf mehrere Attribute einer REST-API-Liste. Einige von ihnen scheinen zu gehen sowohl gegen gängige Praxis und gemeinsame Beratung über SO und anderen Foren. Zum Beispiel:

Ein REST-API sollte ohne Vorkenntnisse über die ursprünglichen URI (Lesezeichen) und eine Reihe von standardisierten Medientypen eingegeben wird, die für die Zielgruppe geeignet sind (dh erwartet von jedem Client zu verstehen, die das verwenden könnten, API). ...
A REST API sollte keine festen Ressourcennamen oder Hierarchien definieren (eine offensichtliche Kopplung von Client und Server). ...
Ein REST-API sollte für die Darstellung von Ressourcen und Fahranwendungszustand oder bei der Definition erweiterten Beziehung Namen und / oder Hypertext-fähigen Aufschlags verwendete bei der Definition des (n) Medientypen fast alle seiner deskriptiven Mühe aufwenden für bestehende Standardmedientypen. ...

Die Idee der „Hypertext“ spielt eine zentrale Rolle - viel mehr als URI-Struktur oder welche HTTP-Verben bedeuten. „Hypertext“ wird in einem der Kommentare definiert:

Wenn ich [Fielding] Hypertext sage, meine ich die gleichzeitige Darstellung von Informationen und Kontrollen, so dass die Informationen die affordance wird, durch die der Benutzer (oder Automaten) erhält Entscheidungen und wählt Aktionen. Hypermedia ist nur eine Erweiterung auf welcher Text bedeutet zeitliche Anker innerhalb eines Medienstroms aufzunehmen; die meisten Forscher haben die Unterscheidung gesunken.

Hypertext muss nicht HTML auf einem Browser sein. Maschinen können Links folgen, wenn sie das Datenformat und Beziehungstypen zu verstehen.

Ich vermute, an diesem Punkt, aber die ersten beiden oben genannten Punkte scheinen, dass die API-Dokumentation für eine Foo Ressource vorzuschlagen, die zwischen Client und Server wie den folgenden führt zu enge Kopplung sieht aus und hat keinen Platz in einer RESTful-System.

GET   /foos/{id}  # read a Foo
POST  /foos/{id}  # create a Foo
PUT   /foos/{id}  # update a Foo

Stattdessen sollte ein Agent gezwungen werden, um die URIs für alle Foos durch zum Beispiel zu entdecken, eine GET-Anfrage an / foos Ausgabe. (Diese URIs kann sich herausstellen, das Muster oben zu folgen, aber das ist nebensächlich.) Die Antwort verwendet einen Medientyp, vermitteln kann, wie jedes Element zugreifen und was mit ihr geschehen, was zu dem dritten Punkt geben oben . Aus diesem Grund sollte die API-Dokumentation konzentriert sich auf zu erklären, wie die Hypertext in der Antwort enthalten sind, zu interpretieren.

Darüber hinaus jedes Mal, wenn ein URI auf eine Foo Ressource angefordert wird, enthält die Antwort alle Informationen für einen Agenten benötigt, um herauszufinden, wie durch zu gehen, zum Beispiel den Zugriff auf assoziierte und Mutter Ressourcen durch ihre URIs oder durch Maßnahmen zu ergreifen nach der Erstellung / Löschung einer Ressource.

Der Schlüssel für das gesamte System ist, dass die Reaktion von Hypertext in einem Medientyp enthalten besteht, die sich an die Agentenoptionen für Verfahren vermittelt. Es ist nicht anders als die Art und Weise ein Browser für die Menschen funktioniert.

Aber das ist nur meine beste Vermutung in diesem Augenblick.

Fielding hat ein Follow-up , in dem er auf die Kritik reagiert, dass seine Diskussion zu abstrakt war, in den Beispielen fehlt und Jargon reichen:

Andere werden versuchen zu entziffern, was ich in einer Weise geschrieben, die mehr direkte oder für einige praktische Anliegen heute. Ich wahrscheinlich nicht, denn ich bin zu beschäftigt mit dem nächsten Thema festhalten, für eine Konferenz vorbereitet, einen anderen Standard zu schreiben, zu einem entfernten Ort reisen, oder einfach nur die kleinen Dinge, die mich lassen glaube, ich habe ich mein Gehalt verdient.

Also, zwei einfache Fragen für die REST-Experten da draußen mit einer praktischen Einstellung: Wie interpretieren Sie was Fielding sagt und wie man es in der Praxis Sie setzen, wenn die Dokumentation / Umsetzung REST APIs

Edit: diese Frage ist ein Beispiel dafür, wie schwer es sein kann, etwas zu lernen, wenn Sie keinen Namen haben, was du redest. Der Name ist in diesem Fall "Hypermedia als Motor der Application State" (HATEOAS).

Lösung

Ich denke, Ihre Erklärung es meist bedeckt. URIs sind opake Kennungen, die über die Lesezeichen werden sollte, nicht URI kommuniziert zum größten Teil, die durch den User-Agent für den Zugriff auf die App verwendet wird.

Wie bei Dokumentieren, diese Frage wurde schon einige Male getan. Sie dokumentieren Sie Ihren Medientyp, zusammen mit der Hyperlink steuert, dass es (Links und Formulare) enthält, und das Interaktionsmodell, wenn Sie so wollen (siehe AtomPub).

Wenn Sie die URIs dokumentieren oder wie sie zu bauen, Sie tun es falsch.

Andere Tipps

Ihre Interpretation scheint mir richtig. Ich glaube, dass Fielding Einschränkungen können praktisch angewandt werden.

Ich möchte wirklich sehen, dass jemand ein paar gute Beispiele veröffentlichen, wie eine REST-Schnittstelle zu dokumentieren. Es gibt so viele schlechte Beispiele, haben einige gültige diejenigen Benutzer zu Punkt sehr wertvoll wäre.

Ich habe ein gutes Beispiel für eine API Suche nach dem HATEOAS geschrieben und hatte Probleme bei der Suche ein (I sowohl die SunCloud gefunden API und AtomPub Sachen schwer zu einer „normalen“ API Situation anzuwenden). So habe ich versucht, ein realistisches Beispiel auf meinem Blog zu machen, dass Roy Fieldings Rat befolgt, was es bedeutet, eine richtige REST Umsetzung. Ich fand es sehr schwierig, mit dem Beispiel zu kommen, trotz der Tatsache, dass es im Prinzip recht einfach ist (nur verwirrend, wenn sie mit einer API, im Gegensatz zu einer Webseite arbeiten). Ich erhalte, was Roy nahm Problem mit und stimmen zu, es ist nur eine Verschiebung in der Haltung richtig für eine API zu implementieren.

Haben Sie einen Blick: API Beispiel mit Rast

Die einzige Ausnahme geben Anleitung, wie URIs zu bauen ist, dass es zulässig ist, eine URI-Vorlage in der Hypertext-Antwort zu senden, mit Feldern automatisch vom Client ersetzt werden, mit anderen Bereichen in dem Hypertext. Dies gilt in der Regel nicht am Ende, obwohl viel Bandbreite eingespart, da die gzip-Komprimierung die wiederholten Teile von URIs gut genug, um sich nicht die Mühe mit dieser behandelt.

Einige gute Diskussionen über REST und die damit verbundenen HATEOAS:

Vorteile: (Auch) Mit HATEOAS In RESTful APIs

Wie eine Tasse Kaffee GET

Für Interessenten, fand ich ein ausführliches Beispiel HATEOAS in der Praxis in der Sun Cloud API .

Die Sache, dass die meisten Menschen falsch ist, dass (zumindest glaube ich) in der REST-Welt, die Sie nicht Ihre „Rest-Schnittstelle“ dokumentieren, was Sie dokumentieren ein Medientyp, unabhängig von Ihrem Server oder Dienst.

Absolut richtig. Ich würde zusätzlich beachten Sie, dass diese URI-Vorlagen innerhalb einer RESTful Anwendung völlig in Ordnung sind, solange die Muster sind aus den Dokumenten vom Server empfangen (OpenSearch- ein geeignetes Beispiel). Für URI-Vorlagen, dokumentieren Sie, wo sie verwendet wird, und dem, was die erwarteten Platzhalter in der Vorlage sind, aber nicht die Vorlagen selbst. Etwas entgegen dem, was Wahnfrieden sagte, ist dies keine Ausnahme.

Zum Beispiel bei meiner Arbeit haben wir ein internes Domain-Management-System, und der Service Dokument legt zwei URI-Vorlagen: ein für eine beste Vermutung URI für eine Domain Ressource produzieren, und eine andere für ein URI Konstruktion für Domain-Verfügbarkeit abfragen. Es ist immer noch möglich, um durch die Sammlung Domains, um herauszufinden, was die URI einer bestimmten Domäne ist, aber die immense Anzahl von Domains gegeben es schafft, das nicht für den Kunden möglich sein würde, so sie einen Weg geben zu erraten, was die URI eines Domain-Ressource sein könnte ist ein großer Gewinn im Hinblick auf die Einfachheit der Implementierung aus Sicht des Kunden, und die Bandbreite vom Server des.

Auf Ihre Frage: Unsere normative Dokumentation ausgesetzt Ressourcen, die Wirkung verschiedener Methoden auf diesen Ressourcen und die Darstellung Medientypen verwendet und deren Schemata, und welche Art von Ressourcen die URIs in diesen representions zu Punkt

Wir sind auch nicht-normative (informativ) Dokumentation, die ihm eine Verzichtserklärung beigefügt ist, nicht zu viel in die URIs in dem Dokument erwähnt zu lesen, die Beispiele von typischen Client-Server-Interaktionen gibt. Damit ist die eher abstrakte normative Dokumentation konkret.

ich über die Anzahl der Jahre denken, dass REST jetzt da draußen war, haben Technologen, sich mit dem Konzept einer Ressource kommen und was wirklich ist oder nicht RESTful.

Nach dem Richardson Maturity Model gibt es 4 Stufen (0-3), die definieren, wie RESTful API ist, mit 3 Bedeutung eines wirklich RESTful API, wie Roy Fieldings es sein sollte.

Stufe 0 ist, wenn Sie einen Einstiegspunkt URI haben -. Wie SOAP

Stufe 1 bedeutet, dass die API der Lage ist, zwischen verschiedenen Ressourcen zu unterscheiden, und mehr als ein Einstiegspunkt hat -. Noch riecht nach SOAP

Stufe 2 ist, wenn Sie HTTP-Verben verwenden - GET, POST, in erster Linie DELETE. Dies ist die Ebene, auf dem REST wirklich ins Bild kommt.

Auf Stufe 3 starten Sie Hypermedia-Kontrollen mit Ihrem API machen wirklich RESTful.

Empfohlene Links für weiterführende Literatur:

Nehmen wir an, GET /foos/createForm aufgerufen wird, um Formularfelder Werte, für die bekommen müssen zur Verfügung gestellt werden, wenn wir POST /foos erstellen gehen. Nun ist diese bestimmte URL d.h die 1 verwendet foos erstellen sollte innerhalb der Antwort für GET /foos/createForm als einreichen Aktionslink nach Fielding Satz erwähnt werden, nicht wahr?
Was ist dann der Vorteil der Mapping-Aktionen zu bekannten Http Verben Aktionen „Konvention über Code / config“ Ding zunichte gemacht wird.

Lizenziert unter: CC-BY-SA mit Zuschreibung

Nicht verbunden mit StackOverflow