it-swarm.com.de

Was bietet HATEOAS für die Auffindbarkeit und Entkopplung neben der Möglichkeit, Ihre URL-Struktur mehr oder weniger frei zu ändern?

In letzter Zeit habe ich über Hypermedia als Engine of Application State (HATEOAS) gelesen, die Einschränkung, die behauptet, eine Web-API "wirklich RESTful" zu machen. Es läuft darauf hinaus, im Grunde genommen Links zu jeder Antwort auf die möglichen Übergänge einzuschließen, die Sie vom aktuellen Status aus vornehmen können.

Lassen Sie mich veranschaulichen, was HATEOAS auf meinem Verständnis basiert - und bitte korrigieren Sie mich, wenn ich etwas verpasst habe.

/
    GET: {
        "_links": {
            "child": [
                { "href": "http://myapi.com/articles", "title": "articles" }
            ]
        }
    }

/articles?contains=HATEOAS
    GET: {
        "_items": [
            { "uri": "http://myapi.com/articles/0", "title": "Why Should I Care About HATEOAS?" },
            { "uri": "http://myapi.com/articles/1", "title": "HATEOAS: Problem or Solution?" }
        ],
        "_links": {
            "self": { "href": "http://myapi.com/articles", "title": "articles" },
            "parent": { "href": "http://myapi.com/", "title": "home" }
        }
    }

    POST: {
        "title": "A New Article",
        "body": "Article body",
        "tags": [ "tag1", "tag2" ]
    }

/articles/0
    GET: {
        "title": "Why Should I Care About HATEOAS?",
        "body": "Blah blah blah"
        "tags": [ "REST", "HATEOAS" ],
        "_links": {
            "self": { "href": "http://myapi.com/articles/0", "title": "article" },
            "parent": { "href": "http://myapi.com/articles", "title": "articles" }
        }
    }

HATEOAS soll zwei Hauptvorteile bieten:

  1. Der gesamte Dienst ist ab dem Root-URI erkennbar, eine Dokumentation wird nicht mehr benötigt.

  2. Der Client ist vom Server entkoppelt, der nun die URI-Struktur frei ändern kann. Dadurch entfällt die Notwendigkeit einer API-Versionierung.

Meiner Ansicht nach ist ein Dienst jedoch viel mehr als seine URI-Struktur. Um es effektiv zu nutzen, müssen Sie außerdem wissen:

  • welche Abfrageparameter können Sie verwenden und welche Werte sind möglich?
  • die Struktur des JSON/XML/aller Dokumente, die Sie zum Senden Ihrer POST/PATCH/etc-Anforderungen benötigen
  • die Struktur der vom Server gesendeten Antwort
  • die möglichen Fehler, die auftreten könnten
  • ...

Basierend auf dem oben Gesagten löst HATEOAS nur einen winzigen Bruchteil der Auffindbarkeits- und Kopplungsprobleme. Sie müssen die oben genannten vier Aspekte noch dokumentieren, und Clients sind aufgrund dieser Aspekte weiterhin stark an den Server gekoppelt. Um zu vermeiden, dass Clients beschädigt werden, müssen Sie Ihre API noch versionieren.

Der einzige Vorteil ist, dass Sie Ihre URL-Struktur mehr oder weniger frei ändern können (übrigens, was ist mit dem Prinzip passiert "Coole URIs ändern sich nicht" ?). Ist mein Verständnis richtig?

63
Botond Balázs

Ich denke, Ihre Instinkte sind weitgehend richtig; Diese proklamierten Vorteile sind wirklich nicht so toll, da sich die Kunden bei jeder nicht trivialen Webanwendung um die Semantik ihrer Arbeit sowie die Syntax kümmern müssen.

Das heißt aber nicht, dass Sie Ihre Bewerbung nicht den Prinzipien von HATEOAS folgen lassen sollten!

Was bedeutet HATEOAS wirklich? Es bedeutet , Ihre Anwendung so zu strukturieren , dass sie im Prinzip wie eine Website ist , und dass alle Vorgänge, die Sie möglicherweise ausführen möchten, erkannt werden können, ohne dass ein komplexes Schema heruntergeladen werden muss. (Anspruchsvolle WSDL-Schemata können alles abdecken, aber zu dem Zeitpunkt, an dem sie dies tun, haben sie die Fähigkeit praktisch jedes Programmierers übertroffen, jemals zu verstehen, geschweige denn zu schreiben! Sie können HATEOAS als Reaktion auf diese Komplexität betrachten.)

HATEOAS bedeutet nicht nur reichhaltige Links. Es bedeutet , die Fehlermechanismen des HTTP-Standards zu verwenden, um genauer anzuzeigen, was schief gelaufen ist. Sie müssen nicht nur mit „waaah! nein “und kann stattdessen ein Dokument bereitstellen, in dem beschrieben wird, was tatsächlich falsch war und was der Kunde möglicherweise dagegen tun könnte. Es bedeutet auch Unterstützung Dinge wie OPTIONS-Anfragen (die Standardmethode, mit der Clients herausfinden können, welche HTTP-Methoden sie verwenden können) und Aushandlung des Inhaltstyps , damit das Format der Antwort an ein Formular angepasst werden kann, das Clients verarbeiten können. Es bedeutet, erklärenden Text (oder wahrscheinlicher Links dazu) einzufügen, damit Clients nachschlagen können, wie das System in nicht trivialen Fällen verwendet wird wenn sie es nicht wissen; Der erklärende Text ist möglicherweise für Menschen lesbar oder maschinenlesbar (und kann so komplex sein, wie Sie möchten). Schließlich bedeutet dies, dass Clients keine Links synthetisieren (mit Ausnahme von Abfrageparametern). Kunden verwenden einen Link nur, wenn Sie ihn ihnen mitgeteilt haben.

Sie müssen darüber nachdenken, die Site von einem Benutzer durchsuchen zu lassen (der JSON oder XML anstelle von HTML lesen kann, also etwas seltsam), mit einem großartig Speicher für Links und einem enzyklopädischen Wissen über HTTP Standards, aber sonst keine Kenntnisse darüber, was zu tun ist.

Natürlich können Sie die Aushandlung von Inhaltstypen verwenden, um einen HTML (5)/JS-Client bereitzustellen, mit dem sie Ihre Anwendung verwenden können, wenn ihr Browser dies akzeptiert. Wenn Ihre RESTful-API gut ist, sollte es schließlich „trivial“ sein, sie zusätzlich zu implementieren?

49
Donal Fellows

Die Sache ist, HATEOAS muss mit einer zweiten Säule kommen, die definiert, was eine RESTful-API ist: standardisierter Medientyp. sagte Roy selbst

Eine REST API sollte fast den gesamten beschreibenden Aufwand für die Definition der Medientypen verwenden, die zur Darstellung von Ressourcen verwendet werden. ".

Mit einem standardisierten Medientyp, der den Übergang explizit definiert, und Hypertext, um Ressourcen aufeinander zu verweisen, können Sie ein Ressourcendiagramm erstellen, das jede Form annehmen kann, ohne einen Client zu beschädigen. Genau wie bei der Webarbeit: Sie haben eine Verknüpfung zwischen Dokument und Dokument sind in HTML geschrieben, das definiert, wie diese Verknüpfungen verfolgt werden sollen. <a href> ist ein GET, <form> ist GET oder POST (und definieren Sie die URL-Vorlage, die im Fall von GET verwendet werden soll), <link type="text/css"> is GET ... etc. So können Browser in beliebig strukturierten HTML-Seiten und im Web navigieren.

Der ganze Punkt, den Sie gemacht haben

  • welche Abfrageparameter können Sie verwenden und welche Werte sind möglich?
  • die Struktur des JSON/XML/aller Dokumente, die Sie zum Senden Ihrer POST/PATCH/etc-Anforderungen benötigen
  • die Struktur der vom Server gesendeten Antwort
  • die möglichen Fehler, die auftreten könnten

Sind Punkte, die angesprochen werden sollten nach der Definition Ihres standardisierten Medientyps. Dies ist natürlich viel schwieriger und nicht etwas, woran die meisten Leute denken, wenn sie eine "REST" -API definieren. Sie können Ihre Geschäftsentitäten nicht einfach in ein JSON-Dokument verschieben, um eine RESTful-API zu erhalten.

Was passiert ist, ist natürlich REST wurde irgendwie verwässert, um "HTTP anstelle von kompliziertem SOAPy-Ding verwenden" zu bedeuten. Nur HTTP und HyperText zu verwenden, reicht nicht aus, um RESTful zu sein, das ist es, was die meisten Leute falsch machen .

Nicht, dass dies für schlechte Dinge notwendig wäre: REST opfern Leistung und einfache Entwicklung im Austausch für längerfristige Wartbarkeit und Evolutivität. Es wurde für die Integration großer Unternehmensanwendungen entwickelt. Eine kleine Web-API mit Eine hartcodierte JSON-Struktur könnte das sein, was Sie brauchen. Nennen Sie sie einfach nicht REST, es ist eine Ad-hoc-Web-API, nichts weiter. Und das bedeutet nicht, dass sie scheiße ist, sondern nur, dass sie nicht versucht, der zu folgen Einschränkung von REST.

Weiterführende Literatur

Hoffe das hilft ein bisschen zu klären :)

Es gibt einige Hypermedia-Formate, die sich bemühen, umfassendere Antworten bereitzustellen, die mehr Informationen darüber enthalten, welche Art von Anfragen gesendet werden sollen, und nichts hindert Sie daran, die Antwort mit noch mehr Informationen anzureichern.

Hier ist ein Beispiel Sirene Dokument:

{
  "class": [ "order" ],
  "properties": { 
      "orderNumber": 42, 
      "itemCount": 3,
      "status": "pending"
  },
  "entities": [
    {
      "class": [ "info", "customer" ],
      "rel": [ "http://x.io/rels/customer" ], 
      "properties": { 
        "customerId": "pj123",
        "name": "Peter Joseph"
      },
      "links": [
        { "rel": [ "self" ], "href": "http://api.x.io/customers/pj123" }
      ]
    }
  ],
  "actions": [
    {
      "name": "add-item",
      "title": "Add Item",
      "method": "POST",
      "href": "http://api.x.io/orders/42/items",
      "type": "application/x-www-form-urlencoded",
      "fields": [
        { "name": "orderNumber", "type": "hidden", "value": "42" },
        { "name": "productCode", "type": "text" },
        { "name": "quantity", "type": "number" }
      ]
    }
  ],
  "links": [
    { "rel": [ "self" ], "href": "http://api.x.io/orders/42" },
    { "rel": [ "previous" ], "href": "http://api.x.io/orders/41" },
    { "rel": [ "next" ], "href": "http://api.x.io/orders/43" }
  ]
}

Wie Sie sehen können, enthält die Nachricht Informationen zum Aufrufen des zugehörigen actions. Durch die Interpretation dieser Informationen wird der Client widerstandsfähiger gegen Änderungen.

Es wird besonders leistungsfähig, wenn rels URIs sind, die nachgeschlagen werden können, anstatt aus einem festen Vokabular.

2
mcintyre321

(HATEOAS), die Einschränkung, die behauptet, eine Web-API "wirklich RESTful" zu machen.

Das einzige, was es zu einer echten REST API macht, ist die Erfüllung aller Einschränkungen, nicht nur einer einzigen.

Meiner Ansicht nach ist ein Dienst jedoch viel mehr als seine URI-Struktur. Um es effektiv zu nutzen, müssen Sie auch wissen: ...

Deshalb brauchen wir die anderen Einschränkungen, die selbstbeschreibende Botschaft usw.

Um zu vermeiden, dass Clients beschädigt werden, müssen Sie Ihre API noch versionieren.

Unabhängig davon, wie Sie es versuchen, müssen Sie Ihre API versionieren. In einem REST Client müssen Sie noch wissen, wie Sie zu einer Seite gelangen, auf der Sie Dinge erledigen möchten, welche Links zu folgen sind und welche Eigenschaften Sie basierend auf dem Vokabular RDF sammeln müssen Beschreibung der Nachricht. Wenn Sie etwas aus diesem Vokabular ersetzen oder entfernen müssen, werden wahrscheinlich alle Ihre Clients beschädigt und Sie benötigen eine neue Version. Daher denke ich, dass Sie [REST nicht frühzeitig veröffentlichen sollten (und das Modell herausfinden sollten, während Sie die API ständig ändern), da Sie sonst viele Versionen haben. Sie benötigen zunächst ein stabiles Domain-Modell, auf dem Sie aufbauen können ...

0
inf3rno

Wo haben Sie gelesen, dass für HATEAOS-Dienste keine Dokumentation mehr benötigt wird? Wie Sie sagen, müssen Sie noch die Semantik der Links dokumentieren. Mit HATEOAS müssen Sie jedoch die Struktur der meisten URIs nicht dokumentieren und daher für immer behalten.

Mit HATEOAS kann ein Service-Implementierer die Implementierung erheblich und effizient ändern und skalieren, ohne einen kleinen Satz von URIs zu ändern, von denen der Client abhängt. Es ist einfacher, eine kleine Anzahl von Einstiegspunkten unverändert zu lassen als einen großen Satz. Wenn Sie also die Anzahl der öffentlichen Einstiegspunkte für den Dienst reduzieren und dynamisch Links zu Unterressourcen (HATEOAS) bereitstellen, werden "Coole URIs ändern sich nicht" besser unterstützt als bei Nicht-HATEOAS-Diensten.

0
Jonathan Giddy