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).