"Und du hast ihm geglaubt?" Sagte der Hufombudsmann vorwurfsvoll. "Nun, was denkst du, hätte ich diese Gewichte ohne deine Erlaubnis genommen?"
"Also hast du die Gewichte genommen?" Weinte Ostap. - Warum?
- Panikovsky sagte, dass sie Gold sind.
Ostap sah Panikovsky an. Erst jetzt bemerkte er, dass unter seiner Jacke nicht mehr als eine fünfzig-Dollar-Hemdfront war und von dort aus blickte Gottes nackter Blick auf das Tageslicht. Ohne ein Wort fiel der große Kombinator auf einen Stuhl. Er zitterte und fing seine Hände in der Luft auf. Dann brachen vulkanische Grollen aus seinem Hals, Tränen rannen aus seinen Augen und Gelächter, das die Müdigkeit der Nacht und die Enttäuschung im Kampf mit Koreiko, der von seinen Milchbrüdern so erbärmlich parodiert wurde, beeinflusste.
Mit diesem Fragment aus den Klassikern möchte ich die Übersetzung des Roy T vorwegnehmen. Fielding-Blogposts REST-APIs müssen hypertextgetrieben sein. Besonderer Dank geht an
habr.com/users/arthuriantech für den Link zum Material.
Diese Woche auf Habré wurde als die Woche der REST (Full) API markiert. In diesem Sinne hat mich das Vorhandensein des REST-Präfixes in diesem Begriff immer verwirrt. Und wie sich herausstellte, nicht nur ich. Heute werde ich es selbst lesen und alle einladen, herauszufinden, was Roy T. Fielding 2008 darüber gedacht hat. Natürlich schleicht sich jemand nervös auf einen Hocker und sagt: Sag es Roy, Benya weiß es für die REST-API. Trotzdem werden wir anfangen.
Ich bin enttäuscht darüber, wie viele Leute eine Schnittstelle aufrufen, die auf der REST-API des HTTP-Protokolls basiert. Das heutige Beispiel ist die REST SocialSite-API. Dies ist ein RPC. Dies ist ein offensichtlicher RPC. Es zeigt so harte Verbindungen, dass es Zeit für ihn ist, die Kategorie harter Pornos zuzuweisen.
Was muss getan werden, damit sie verstehen, dass Hypertext ein notwendiges Element in der REST-Architektur ist? Mit anderen Worten, wenn der Mechanismus für den Anwendungsstatus (und damit die API) nicht auf Hypertext basiert, kann er nicht REST-konform sein und keine REST-API sein. Der Punkt. Welches Buch sollte ich umschreiben, um es klar zu machen?
Beachten Sie die folgenden Regeln, bevor Sie Ihre REST-API-Erstellungen aufrufen:
Die REST-API sollte nicht von einem bestimmten Kommunikationsprotokoll abhängig sein, obwohl ihre erfolgreiche Zuordnung zu diesem Protokoll von der Verfügbarkeit von Metadaten, der Auswahl von Methoden usw. abhängen kann. Im Allgemeinen sollte jedes Protokoll in einem URI-Schema die Verwendung eines URI-Schemas zur Identifizierung ermöglichen. [Der Fehler hierbei ist, dass die Identifikation nicht von der Interaktion getrennt ist.]
Die REST-API sollte keine Änderungen an den Kommunikationsprotokollen enthalten, außer das Ausfüllen oder Korrigieren der Details unzureichend definierter Bits von Standardprotokollen wie der PATCH-HTTP-Methode oder des Link-Header-Felds. Problemumgehungen für nicht funktionierende Implementierungen (z. B. Browser, die nicht der Meinung sind, dass HTML eine Reihe von HTTP-Methoden definiert) müssen separat oder zumindest in Anwendungen mit der Erwartung festgelegt werden, dass die Problemumgehung möglicherweise veraltet ist. [Der Fehler hierbei ist, dass die Ressourcenschnittstellen spezifisch und nicht universell sind.]
Die REST-API sollte fast den gesamten beschreibenden Aufwand für die Definition der zur Darstellung von Ressourcen verwendeten Medientypen und die Verwaltung des Anwendungszustands sowie für die Definition erweiterter Beziehungs- und Hypertext-Markup-Namen für vorhandene Standardmedientypen verwenden. Jeder Aufwand, der aufgewendet wird, um zu beschreiben, welche Methoden mit welchen URIs von Interesse verwendet werden sollen, sollte als Teil der Verarbeitungsregeln für den Medientyp (und in den meisten Fällen bereits durch vorhandene Medientypen definiert) vollständig definiert werden. [Der Fehler hierbei ist, dass Informationen außerhalb der Ressource die Interaktion anstelle von Hypertext steuern.]
Die REST-API sollte keine festen Ressourcennamen oder Namespaces definieren (enge Client-Server-Konnektivität). Server müssen die Freiheit haben, ihre eigenen Namespaces zu verwalten. Lassen Sie stattdessen die Server die Clients anweisen, wie die entsprechenden URIs erstellt werden sollen, z. B. in HTML-Formularen und URI-Vorlagen. Definieren Sie diese Anweisungen in Medientypen und Referenzbeziehungen. [Der Fehler hierbei ist, dass die Struktur der Ressource außerhalb dieser Ressource festgelegt ist, z. B. in einem domänenspezifischen Standard, der eigentlich ein Analogon der RPC-Funktionsbeziehung ist].
Die REST-API sollte niemals Ressourcen "eingegeben" haben, die für den Client von Bedeutung sind. Spezifikationsautoren können Ressourcentypen verwenden, um die Serverimplementierung hinter der Schnittstelle zu beschreiben. Diese Typen müssen jedoch irrelevant und für den Client unsichtbar sein. Die einzigen Typen, die für den Kunden wichtig sind, sind der Medientyp der aktuellen Ansicht und standardisierte Beziehungsnamen. [siehe oben]
Die REST-API sollte ohne Vorkenntnisse außer der ursprünglichen URI und einer Reihe standardisierter Medientypen eingegeben werden, die für die Zielgruppe geeignet sind (d. H. Auf Kundenseite erwartet, die die API verwenden kann). Ab diesem Moment sollten alle Übergänge der Anwendungszustände durch die Auswahl der Optionen bestimmt werden, die der Server in den empfangenen Ansichten bereitstellt, oder durch die Manipulationen des Benutzers mit diesen Ansichten. Übergänge können durch das Wissen des Kunden über die Arten von Medien- und Ressourcenkommunikationsmechanismen bestimmt (oder begrenzt) werden, die im laufenden Betrieb verbessert werden können (z. B. Code auf Anfrage). [Der Fehler hierbei ist, dass Informationen außerhalb der Ressource die Interaktion anstelle von Hypertext steuern.]
Vielleicht habe ich etwas verpasst, aber die oben genannten Regeln sind für Hypertext unerlässlich und werden in der sogenannten REST-API am häufigsten verletzt. Bitte versuchen Sie, bei ihnen zu bleiben oder wählen Sie ein anderes Schlagwort für Ihre API.
Dieser Beitrag von Roy T. Fielding löste eine Diskussion in den Kommentaren aus. Ich schlage vor, mich mit dem Teil der Diskussion vertraut zu machen, der von den Antworten des Autors begleitet wurde.
Frage:
Inwiefern verwenden Sie hier den Begriff "Hypertext"? Muss ich Ihre Arbeit lesen, um zu verstehen, was Sie meinen, oder gibt es etwas im Internet, das die Bedeutung dieses Konzepts verrät?
Die Antwort lautet:
Ich habe eine Folie in meinem REST-Vortrag, die erklärt, was Hypertext (und Hypermedien) bedeuten.
Hypertext hat viele Definitionen:
Die ursprüngliche Definition von Ted Nelson konzentrierte sich auf nichtlineare Dokumente.
Mit „Hypertext“ meine ich ein nicht lineares Dokument - ein Text, der den Leser auffordert und ihm ermöglicht, eine Auswahl zu treffen, ein Dokument, das auf einem interaktiven Bildschirm einfach zu lesen ist. Es ist allgemein anerkannt, dass dies eine Folge von Textblöcken ist, die durch Links verbunden sind, die dem Leser verschiedene Routen anbieten. [Theodore H. Nelson]
Hypertext wurde später mit einem bestimmten Benutzeroberflächenmechanismus verknüpft.
Hypertext ist ein computergestütztes Speichermedium, auf dem verwandte Dokumente mit ihren Links auf einem hochauflösenden Computerbildschirm angezeigt werden. [Jeffrey Conklin]
Wenn ich "Hypertext" sage, meine ich die gleichzeitige Darstellung von Informationen und Steuerelementen in einer Weise, dass die Informationen verfügbar werden, wodurch der Benutzer (oder die Maschine) eine Auswahl erhält und Aktionen auswählt. Hypermedia ist einfach eine Erweiterung dessen, was der Text bedeutet, um temporäre Anker in den Medienstream aufzunehmen. Die meisten Forscher lehnten diese Unterscheidung ab.
Hypertext muss für den Browser kein HTML-Code sein. Maschinen können Verknüpfungen folgen, wenn sie das Datenformat und die Beziehungstypen verstehen.
Dave Johnson (Autor der kritisierten API):
Vielleicht habe ich eine unscharfe Formulierung gegeben. Ich wollte nie behaupten, dass die OpenSocial- oder SocialSite-RPC-APIs REST-fähig sind. Mehr auf meinem Blog rollerweblogger.org/roller/entry/the_x_rated_socialsite_api .
Die Antwort lautet:
Das OpenSocial RESTful-Protokoll ist nicht RESTful. Dies kann mit relativ geringen Änderungen behoben werden. Jetzt werden nur noch die RPC-Ergebnisse in gängige Webmedientypen gepackt.
Die echte RESTful-API sieht aus wie Hypertext. Jede adressierbare Informationseinheit trägt eine Adresse, entweder explizit (zum Beispiel Link- und ID-Attribute) oder implizit (zum Beispiel aus der Definition des Medientyps und der Präsentationsstruktur). Die Abfrageergebnisse werden durch eine Liste von Links mit zusammenfassenden Informationen dargestellt und nicht durch Arrays von Objektdarstellungen (die Abfrage ersetzt nicht die Ressourcenidentifikation). Ressourcendarstellungen sind selbstdokumentierend: Der Client muss nicht wissen, ob es sich bei dieser Ressource um eine OpenSocialist-Ressource handelt, da sie sich lediglich auf die empfangenen Darstellungen auswirkt.
Denken Sie an das Internet. Wie vielen Webbrowsern ist der Unterschied zwischen einer Online-Banking-Ressource und einem Wiki bekannt? Keiner von ihnen. Sie müssen nicht über Ressourcentypen Bescheid wissen. Was sie wissen müssen, sind mögliche Zustandsübergänge: Verknüpfungen und Formen und welche Art von Semantik oder Aktion impliziert das Überqueren dieser Verknüpfungen. Der Browser präsentiert sie als separate Steuerelemente der Benutzeroberfläche, sodass der Benutzer potenzielle Übergänge sehen und die Auswirkung der ausgewählten Aktionen vorhersehen kann. Bots können ihnen folgen, sofern bekannt ist, dass die Aktionen sicher sind. Typisierte Beziehungen, bestimmte Medientypen und aktionsbezogene Elemente bieten die für automatisierte Agenten erforderliche Anleitung.
Nützliche Links:
1.
Übersetzungsversion von habr.com/us/users/arthuriantech2.
Dieselbe These des alten Roy