Was bietet HATEOAS für 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 wird, eine Web-API "wirklich RESTful" zu machen. Es läuft darauf hinaus, Verknüpfungen mit jeder Antwort auf die möglichen Übergänge, die Sie vom aktuellen Status aus vornehmen können, zu berücksichtigen.

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 wesentliche Vorteile bieten:

1. Der gesamte Dienst ist ab dem Root-URI erkennbar, eine Dokumentation ist nicht mehr erforderlich.

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

Aus meiner Sicht ist ein Service jedoch viel mehr als seine URI-Struktur. Um es effektiv zu nutzen, müssen Sie auch wissen:

• Welche Abfrageparameter können Sie verwenden und deren mögliche Werte
• 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önnen
• ...

Auf dieser Grundlage löst HATEOAS nur einen winzigen Bruchteil der Entdeckbarkeits- und Kopplungsprobleme. Sie müssen die vier oben genannten Aspekte noch dokumentieren, und die Clients sind aufgrund dieser Aspekte weiterhin stark mit dem Server verbunden. 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 "Coole URIs ändern sich nicht" passiert ?). Ist mein Verständnis korrekt?

Ich denke, Ihre Instinkte sind weitgehend richtig; Diese proklamierten Vorteile sind wirklich nicht so großartig, 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 nach den Prinzipien von HATEOAS bewerben sollten!

Was bedeutet HATEOAS wirklich ? Es bedeutet , Ihre Anwendung so zu strukturieren , dass sie im Prinzip einer Website ähnelt und dass alle Vorgänge, die Sie ausführen möchten, ermittelt werden können, ohne dass ein komplexes Schema heruntergeladen werden muss. (Ausgefeilte WSDL-Schemata können alles abdecken, haben aber zu dem Zeitpunkt die Fähigkeit praktisch aller Programmierer übertroffen, jemals zu verstehen, geschweige denn zu schreiben! Sie können HATEOAS als Reaktion auf diese Komplexität ansehen.)

HATEOAS bedeutet nicht nur reichhaltige Links. Es bedeutet , die Fehlermechanismen des HTTP-Standards zu verwenden , um genauer anzuzeigen, was schief gelaufen ist. du musst 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 unternehmen könnte. Es bedeutet auch , unterstützt Dinge wie OPTIONS - Anforderungen (die Standardmethode der so dass Kunden , welche Methoden HTTP , um herauszufinden , die sie verwenden können) und Inhaltstyp Verhandlung , so dass das Format der Antwort kann auf eine Form angepasst werden , dass Kunden umgehen kann. Es bedeutet, einen erläuternden Text einzugeben(oder eher Links dazu), damit Kunden nachschlagen können, wie sie das System in nicht trivialen Fällen verwenden können, wenn sie es nicht wissen. Der erläuternde Text kann von Menschen oder von Maschinen gelesen werden (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, ob die Site von einem Benutzer durchsucht werden soll (der JSON oder XML anstelle von HTML lesen kann, was ein wenig seltsam ist), der über ein großes Gedächtnis für Links und ein enzyklopädisches Wissen über die HTTP-Standards verfügt, ansonsten aber nicht weiß, was zu tun ist machen.

Und natürlich können Sie die Inhaltstypaushandlung verwenden, um einen HTML (5) / JS-Client bereitzustellen, mit dem diese Ihre Anwendung verwenden können, sofern ihr Browser dies akzeptiert. Wenn Ihre RESTful-API eine gute ist, sollte die Implementierung darüber hinaus "trivial" sein?

Die Sache ist, dass HATEOAS eine zweite Säule haben muss, die definiert, was eine RESTful-API ist: standardisierter Medientyp. Sagte Roy, der sich selbst aufstellte

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 im Web: Sie haben eine Verknüpfung zwischen dem Dokument und dem Dokument, die in HTML geschrieben ist und definiert, wie diesen Verknüpfungen gefolgt werden soll. <a href>ist ein GET, <form>ist GET oder POST (und definiert die zu verwendende URL-Vorlage im Fall von GET), <link type="text/css">ist GET ... usw. Auf diese Weise können Browser durch beliebig strukturierte HTML-Seiten und das Web navigieren.

Alles, was Sie gesagt haben

• Welche Abfrageparameter können Sie verwenden und deren mögliche Werte
• 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önnen

Sind Punkte, die durch die Definition Ihres standardisierten Medientyps angesprochen werden sollen . Natürlich ist dies viel schwieriger und nicht etwas, woran die meisten Leute denken, wenn sie eine "REST" -API definieren. Sie können nicht einfach Geschäftsentitäten mitnehmen und deren Attribute in ein JSON-Dokument verschieben, um eine RESTful-API zu erhalten.

Natürlich wurde REST irgendwie verwässert und bedeutete "HTTP anstelle von kompliziertem SOAPy-Ding". Nur HTTP und HyperText zu verwenden, reicht nicht aus, um RESTful zu sein. Dies ist das, was die meisten Leute falsch verstehen.

Nicht, dass dies eine schlechte Sache ist: REST opfert Leistung und einfache Entwicklung im Austausch für längerfristige Wartbarkeit und Entwicklungsfähigkeit. Es wurde für die Integration von Großunternehmensanwendungen entwickelt. Möglicherweise benötigen Sie eine kleine Web-API mit fest codierter JSON-Struktur. Nennen Sie es einfach nicht REST, es ist eine Ad-hoc-Web-API, mehr nicht. Und das heißt nicht, dass es scheiße ist, sondern nur, dass es nicht versucht, den Einschränkungen von REST zu folgen.

Weitere Lektüre

• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven
• http://martinfowler.com/articles/richardsonMaturityModel.html

Hoffe das hilft ein bisschen zu klären :)

Es gibt einige Hypermedia-Formate, die sich bemühen, umfassendere Antworten zu liefern, die weitere Informationen zu den zu sendenden Anforderungen enthalten, und nichts hindert Sie daran, die Antwort mit noch mehr Informationen anzureichern.

Hier ist ein Beispiel für ein Sirenendokument :

{
  "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, enthält actionsdie Nachricht Informationen zum Anrufen. Durch die Interpretation dieser Informationen wird der Client änderungsresistenter.

Besonders mächtig wird es, wenn es sich bei rels um URIs handelt, die nachgeschlagen werden können und nicht aus einem festen Vokabular.

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

Mit HATEOAS kann ein Service-Implementierer die Implementierung erheblich und effizient ändern und skalieren, ohne eine kleine Menge von URIs zu ändern, von denen der Client abhängig ist. Es ist einfacher, eine kleine Anzahl von Eintrittspunkten unverändert zu lassen als eine große Menge. Wenn Sie also die Anzahl der öffentlichen Einstiegspunkte für den Dienst verringern und dynamisch Links zu Subressourcen (HATEOAS) bereitstellen, werden "Coole URIs ändern sich nicht" besser als bei Nicht-HATEOAS-Diensten.

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

Das einzige, was es zu einer echten REST-API macht, ist, alle Einschränkungen zu erfüllen, nicht nur eine einzige.

Aus meiner Sicht ist ein Service jedoch viel mehr als seine URI-Struktur. Um es effektiv zu nutzen, müssen Sie auch wissen: ...

Das ist der Grund, warum wir die anderen Einschränkungen, die selbsterklärende Botschaft usw. brauchen.

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

Egal wie Sie es versuchen, Sie müssen Ihre API versionieren. In einem REST-Client müssen Sie noch wissen, wie Sie zu einer Seite gelangen, auf der Sie Aufgaben erledigen möchten, welche Links zu folgen sind und welche Eigenschaften Sie basierend auf dem RDF-Vokabular erfassen müssen, das die Nachricht beschreibt. 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 sonst viele Versionen zur Verfügung stehen. Sie benötigen zunächst ein stabiles Domain-Modell, auf dem Sie aufbauen können ...