Ist das REST API wirklich RPC? Roy Fielding scheint das zu glauben

Eine große Menge von dem, was ich über REST zu wissen glaubte, ist anscheinend falsch - und ich bin nicht allein. Diese Frage hat einen langen Einstieg, scheint aber notwendig zu sein, da die Informationen etwas verstreut sind. Die eigentliche Frage kommt am Ende, wenn Sie mit diesem Thema bereits vertraut sind.

Aus dem ersten Absatz von Roy Fieldings REST-APIs geht hervor, dass sie hypertextgesteuert sein müssen. Es ist ziemlich klar, dass er glaubt, dass seine Arbeit weitgehend falsch interpretiert wird:

Ich bin frustriert über die Anzahl der Leute, die eine HTTP-basierte Schnittstelle als REST-API bezeichnen. Das heutige Beispiel ist die SocialSite REST-API . Das ist RPC. Es schreit RPC. Es wird so viel Kopplung angezeigt, dass eine X-Bewertung vergeben werden sollte.

In Fielding werden mehrere Attribute einer REST-API aufgelistet. Einige von ihnen scheinen sowohl gegen die gängige Praxis als auch gegen die allgemeinen Ratschläge zu SO und anderen Foren zu verstoßen. Beispielsweise:

• Eine REST-API sollte ohne Vorkenntnisse über den ursprünglichen URI (Lesezeichen) und eine Reihe standardisierter Medientypen hinaus eingegeben werden, die für die beabsichtigte Zielgruppe geeignet sind (dh von jedem Client, der die API möglicherweise verwendet, verstanden werden). ...

• Eine REST-API darf keine festen Ressourcennamen oder -hierarchien definieren (eine offensichtliche Kopplung von Client und Server). ...

• Eine REST-API sollte fast den gesamten beschreibenden Aufwand für die Definition der Medientypen verwenden, die zur Darstellung von Ressourcen und zur Steuerung des Anwendungsstatus verwendet werden, oder für die Definition erweiterter Beziehungsnamen und / oder hypertextfähiger Markierungen für vorhandene Standardmedientypen. ...

Die Idee des "Hypertexts" spielt eine zentrale Rolle - viel mehr als die URI-Struktur oder was HTTP-Verben bedeuten. "Hypertext" wird in einem der Kommentare definiert:

Wenn ich [Fielding] Hypertext sage, meine ich die gleichzeitige Darstellung von Informationen und Steuerelementen, so dass die Informationen zu dem Vorteil werden, durch den der Benutzer (oder Automat) Auswahlmöglichkeiten erhält und Aktionen auswählt. Hypermedia ist nur eine Erweiterung dessen, was Text bedeutet, um zeitliche Anker in einen Medienstrom aufzunehmen. Die meisten Forscher haben die Unterscheidung fallen gelassen.

Hypertext muss in einem Browser kein HTML sein. Maschinen können Links folgen, wenn sie das Datenformat und die Beziehungstypen verstehen.

Ich vermute an dieser Stelle, aber die ersten beiden Punkte oben scheinen darauf hinzudeuten, dass die API-Dokumentation für eine Foo-Ressource, die wie folgt aussieht, zu einer engen Kopplung zwischen Client und Server führt und keinen Platz in einem RESTful-System hat.

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

Stattdessen sollte ein Agent gezwungen sein, die URIs für alle Foos zu ermitteln, indem er beispielsweise eine GET-Anforderung gegen / foos ausgibt. (Es kann sich herausstellen, dass diese URIs dem obigen Muster folgen, aber das ist nicht der Punkt.) Die Antwort verwendet einen Medientyp, der vermitteln kann, wie auf jedes Element zugegriffen wird und was damit getan werden kann, wodurch der dritte Punkt oben entsteht . Aus diesem Grund sollte sich die API-Dokumentation darauf konzentrieren, zu erklären, wie der in der Antwort enthaltene Hypertext zu interpretieren ist.

Darüber hinaus enthält die Antwort jedes Mal, wenn ein URI für eine Foo-Ressource angefordert wird, alle Informationen, die ein Agent benötigt, um herauszufinden, wie er vorgehen soll, indem er beispielsweise über seine URIs auf zugeordnete und übergeordnete Ressourcen zugreift oder nach der Erstellung Maßnahmen ergreift / Löschen einer Ressource.

Der Schlüssel zum gesamten System besteht darin, dass die Antwort aus Hypertext besteht, der in einem Medientyp enthalten ist, der selbst den Agentenoptionen zum Fortfahren übermittelt. Es ist nicht anders als die Art und Weise, wie ein Browser für Menschen funktioniert.

Aber dies ist nur meine beste Vermutung in diesem besonderen Moment.

Fielding veröffentlichte ein Follow-up, in dem er auf die Kritik reagierte, dass seine Diskussion zu abstrakt, ohne Beispiele und umgangssprachlich sei:

Andere werden versuchen, das, was ich geschrieben habe, auf eine Weise zu entschlüsseln, die direkter oder auf ein praktisches Anliegen von heute anwendbar ist. Ich werde es wahrscheinlich nicht tun, weil ich zu beschäftigt bin, mich mit dem nächsten Thema auseinanderzusetzen, mich auf eine Konferenz vorzubereiten, einen anderen Standard zu schreiben, an einen entfernten Ort zu reisen oder einfach nur die kleinen Dinge zu tun, die mir das Gefühl geben, meinen Gehaltsscheck verdient zu haben.

Zwei einfache Fragen an die REST-Experten mit praktischer Denkweise: Wie interpretieren Sie das, was Fielding sagt, und wie setzen Sie es bei der Dokumentation / Implementierung von REST-APIs in die Praxis um?

Bearbeiten: Diese Frage ist ein Beispiel dafür, wie schwierig es sein kann, etwas zu lernen, wenn Sie keinen Namen für das haben, worüber Sie sprechen. Der Name in diesem Fall lautet "Hypermedia als Engine of Application State" (HATEOAS).

Ich denke, Ihre Erklärung deckt es hauptsächlich ab. URIs sind undurchsichtige Kennungen, die größtenteils nicht über die Lesezeichen-URI hinaus kommuniziert werden sollten, die vom Benutzeragenten für den Zugriff auf die App verwendet wird.

In Bezug auf die Dokumentation wurde diese Frage einige Male gestellt. Sie dokumentieren Ihren Medientyp zusammen mit den darin enthaltenen Hyperlink-Steuerelementen (Links und Formulare) und dem Interaktionsmodell, wenn Sie dies wünschen (siehe AtomPub).

Wenn Sie die URIs dokumentieren oder wie sie erstellt werden, machen Sie es falsch.

Ihre Interpretation scheint mir richtig zu sein. Ich glaube, dass die Einschränkungen von Fielding praktisch angewendet werden können.

Ich würde wirklich gerne sehen, dass jemand einige gute Beispiele für die Dokumentation einer REST-Schnittstelle veröffentlicht. Es gibt so viele schlechte Beispiele, dass einige gültige Beispiele, auf die Benutzer hinweisen können, sehr wertvoll wären.

Ich habe nach einem guten Beispiel für eine API gesucht, die nach dem HATEOAS geschrieben wurde, und hatte Probleme, eine zu finden (ich fand es schwierig, sowohl die SunCloud-API als auch AtomPub auf eine "normale" API-Situation anzuwenden). Deshalb habe ich versucht, in meinem Blog ein realistisches Beispiel zu geben, das den Ratschlägen von Roy Fieldings folgte, was es bedeutet, eine ordnungsgemäße REST-Implementierung zu sein. Ich fand es sehr schwierig, ein Beispiel zu finden, obwohl es im Prinzip ziemlich einfach ist (nur verwirrend, wenn man mit einer API im Gegensatz zu einer Webseite arbeitet). Ich verstehe, womit Roy Probleme hatte, und stimme zu, dass es nur eine Änderung der Denkweise ist, eine API richtig zu implementieren.

Schauen Sie sich das an: API-Beispiel mit Rest

Die einzige Ausnahme für Anweisungen zum Erstellen von URIs besteht darin, dass es zulässig ist, eine URI-Vorlage in der Hypertext-Antwort zu senden, wobei Felder vom Client automatisch durch andere Felder im Hypertext ersetzt werden. Dies spart normalerweise nicht viel Bandbreite, da die gzip-Komprimierung die wiederholten Teile von URIs gut genug verarbeitet, um sich nicht darum zu kümmern.

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

Vorteile der (auch) Verwendung von HATEOAS in RESTFul-APIs

Wie man eine Tasse Kaffee bekommt

Für Interessenten habe ich in der Sun Cloud API ein detailliertes Beispiel für HATEOAS in der Praxis gefunden .

Das, was die meisten Leute falsch machen, ist, dass Sie (zumindest glaube ich) in der REST-Welt Ihre "Rest-Schnittstelle" nicht dokumentieren. Was Sie dokumentieren, ist ein Medientyp, unabhängig von Ihrem Server oder Dienst.

Ich denke, über die Anzahl der Jahre, in denen REST jetzt da draußen ist, haben sich Technologen mit dem Konzept einer Ressource und dem, was wirklich REST ist oder nicht, abgefunden.

Gemäß dem Richardson-Reifegradmodell gibt es 4 Ebenen (0-3), die definieren, wie RESTful Ihre API ist, wobei 3 eine wirklich RESTful-API bedeutet, so wie Roy Fielding es beabsichtigt hat.

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

Stufe 1 bedeutet, dass die API zwischen verschiedenen Ressourcen unterscheiden kann und mehr als einen Einstiegspunkt hat - es riecht immer noch nach SOAP.

Stufe 2 ist, wenn Sie hauptsächlich HTTP-Verben verwenden - GET, POST, DELETE. Dies ist die Ebene, auf der REST wirklich ins Bild kommt.

Ab Stufe 3 verwenden Sie Hypermedia-Steuerelemente, um Ihre API wirklich REST- fähig zu machen .

Vorgeschlagene Links zur weiteren Lektüre:

• Was ist das Richardson-Reifegradmodell?
• Martin Fowlers Blog: Richardson Maturity Model

Absolut korrekt. Ich möchte außerdem darauf hinweisen, dass URI-Vorlagen in einer RESTful-Anwendung vollkommen in Ordnung sind, solange die Muster aus vom Server empfangenen Dokumenten stammen (OpenSearch ist ein geeignetes Beispiel). Bei URI-Vorlagen dokumentieren Sie, wo sie verwendet werden und welche Platzhalter in der Vorlage erwartet werden, nicht jedoch die Vorlagen selbst. Etwas im Gegensatz zu Wahnfrieden ist dies keine Ausnahme.

Bei meiner Arbeit haben wir beispielsweise ein internes Domänenverwaltungssystem, und das Servicedokument gibt zwei URI-Vorlagen an: eine zum Erstellen eines Best-Guess-URI für eine Domänenressource und eine zum Erstellen eines URI zum Abfragen der Domänenverfügbarkeit. Es ist weiterhin möglich, durch die Domainsammlung zu blättern, um herauszufinden, wie der URI einer bestimmten Domain lautet. Angesichts der immensen Anzahl der von ihr verwalteten Domains wäre dies für den Client jedoch nicht möglich Der URI einer Domänenressource ist möglicherweise ein großer Gewinn in Bezug auf die einfache Implementierung aus Sicht des Clients und die Bandbreite aus Sicht des Servers.

Weiter zu Ihrer Frage: Unsere normative Dokumentation enthält Ressourcen, die Auswirkungen verschiedener Methoden auf diese Ressourcen, die verwendeten Darstellungsmedientypen und ihre Schemata sowie die Art der Ressourcen, auf die die URIs in diesen Darstellungen verweisen.

Wir fügen auch eine nicht normative (informative) Dokumentation hinzu, der ein Haftungsausschluss beigefügt ist, nicht zu viel in die im Dokument genannten URIs einzulesen, der Beispiele für typische Client-Server-Interaktionen enthält. Damit wird die eher abstrakte normative Dokumentation konkretisiert.

Nehmen wir an, es GET /foos/createFormwird aufgerufen, um Werte für Formularfelder abzurufen, für die beim Erstellen angegeben werden muss POST /foos. Nun sollte diese bestimmte URL, dh die 1, die zum Erstellen von Foos verwendet wird, in der Antwort GET /foos/createFormals Link für Übermittlungsaktionen gemäß Fieldings Vorschlag erwähnt werden, oder?
Was ist dann der Vorteil der Zuordnung von Aktionen zu bekannten HTTP-Verben zu Aktionen? "Konvention über Code / Konfiguration" wird aufgehoben.