Hypermedia-freundliches REST-Muster zum Erstellen und Aktualisieren einer Ressource

Was Sie beschreiben, erinnert mich ein bisschen an Formular-Link-Beziehungen erstellen und bearbeiten . Wenn Sie eine API erstellen, ist ihre Verwendung jedoch ziemlich begrenzt, da Sie jemanden programmieren müssen, unabhängig davon, wie sie definiert ist.

Meiner Meinung nach ist der einfachste Weg, das oben angegebene Beispiel zu organisieren, ein Wurzelmenü wie folgt zu definieren:

Die Beziehung plants würde eine Sammlung von Betriebsressourcen enthalten, die durch einen bestimmten Medientyp definiert sind (sagen wir es application/vnd.biology-example-org.plant ):

Um der Sammlung eine neue Pflanze hinzuzufügen, die mit dem Pastinnip in Verbindung steht, POST an die% collection-Ressource plants und beziehen sich über den Link auf die Parnsip:

Um die Karotte nachträglich zu ändern, geben Sie eine PUT an die URL aus, die zurückgegeben wurde:

Im obigen Beispiel wird die Hypertext Application Language (HAL) verwendet, um die REST-Semantik der Ebene 3 mit JSON zu kommunizieren. HAL ist einfach, aber sehr mächtig. Eine der Konventionen, die ich wirklich mag, ist die Verwendung des Beziehungsnamens als einer URI, die bei einer Dereferenzierung direkt auf die Dokumentation über diese Beziehung und die von ihr zurückgegebenen Ressourcen zeigt.

Wenn Sie mit einer Live-API wie dieser herumspielen möchten, würde ich Ihnen wärmstens empfehlen, HALtalk anzuschauen, was ein Live ist Demo-API von HAL.

Lass uns eine Frage stellen. Was benötigen Sie, um eine Ressource zu bearbeiten?

• Bei HTML benötigen Sie ein FORM-Tag und INPUT-Tags in ihnen.

Was beschreiben sie?

• 1.) Es ist eine Form.
• 2.) Es hat eine Aktion IRI.
• 3.) Es hat eine Methode.
• 4.) Es hat einen Inhaltstyp.
• 5.) Es hat mehrere Felder, die vom Benutzer ausgefüllt werden sollten. Vielleicht mit Validierungsdaten.

In der Form, die du hast:

• 6.) Titel für das gesamte Formular
• 7.) Label für die Eingabefelder

Dies ist fast dasselbe, das ein REST-Client benötigt.

• 8.) Es sollte eine Link-Relation für den REST-Client enthalten, die es bereits kennt, damit der Client es verwendet, um das Formular in den richtigen Kontext zu stellen. (Sie können dies mit RDFa per HTML tun.)

Das ist alles, nicht weniger, nicht mehr.

Sehen wir uns jetzt Ihre aktuellen Optionen anhand meiner beiden Lieblings-JSON-Medientypen an (es gibt viele andere JSON-Hypermedia-Typen, wie z. B. Sammlung + JSON, Shiren usw.).

HAL + JSON

Mit HAL können Sie eingebettete Ressourcen definieren und ihnen Links hinzufügen.

Der _link beschreibt hier die 1.), die href beschreibt hier die 2.), der Linktitel beschreibt die 6.), die Link-Relation beschreibt die 3.) und die 8.). Wir benötigen den Inhaltstyp 4.) und die Metadaten zu den benötigten Feldern: Validierung, Labels 5.) und 7.).

Welche Auswahl haben wir hier?

• Wir können HAL + JSON etwas erweitern und jedem Link oder
eine fields -Eigenschaft hinzufügen
• können wir herstellerspezifische Inhaltstypen hinzufügen, um die Felder zu beschreiben.

JSON-LD + hydra vocab

Durch die hydra Vokabeln können Sie Operationen hinzufügen Ihr hydra:Link s in Ihrem RDF - normalerweise JSON-LD - Dokument.

Ofc. In der Praxis würden Sie den gesamten @ context-Teil in eine separate Datei unter dem IRI /vocab verschieben, aber es ist einfacher, auf diese Weise zu überprüfen, was er tut. Bei RDF-Dokumenten haben Sie Betreff, Prädikat, Zieltripel. Zum Beispiel hier: /issues/cso29ax , /ctx#Issue/title , "Some random issue" kann ein Triplet sein. Also sind "id", "created_at", "title", "comments" nur alternative Namen, die Sie mit @context beschreiben können.

Also hier beschreibt der @context den Kontext der Repräsentation und den Eigenschaftsnamen wie /ctx#create-comment und den Operationsnamen, wie hydra:CreateResourceOperation beschreibt die Link-Relation 8.). Ofc kannst du den iana vocab nach der Beschreibung von /ctx#create-comment benutzen, wenn du willst. Es hängt von Ihnen und den Fähigkeiten Ihres REST-Clients ab. Das hydra:Link beschreibt, dass es sich um ein Formular 1.) handelt. Die @id: "/issues/cso29ax/comments/" beschreibt die Aktion IRI 2.). Das rdfs:label beschreibt den Formulartitel und die Eingabefeldbeschriftungen 6.) und 7.) (es kann mehrsprachig sein). Der Inhaltstyp ist immer JSON + LD 4.). Die HTTP-Methode wird beschrieben durch hydra:method 3.), die Validierungsdaten usw. werden durch hydra:expects und hxdra:returns jeder Eigenschaft beschrieben. 5.) also ist es Teil des "@context" ( Ich habe es im Beispiel weggelassen). Mit RDF + Hydra Vocab brauchen Sie also nichts anderes, um Ihre Formulare zu beschreiben.

Wahrscheinlich müssen Sie mehrere Darstellungen derselben Ressource definieren.

Zum Beispiel brauchen Sie eine Repräsentation mit Erstellungslink, Link bearbeiten, Link löschen, etc ... und Sie benötigen nur eine Darstellung mit Daten. Sie können dies auf verschiedene Arten tun:

• Sie können für jede der Darstellungen einen herstellerspezifischen Inhaltstyp definieren.
• Sie können eine neue IRI für Ihre Ressource hinzufügen, z. B. /issues/?data-only=1 . (Die Abfrage bezieht sich auf den nicht-hierarchischen Teil der IRIs, daher ist sie auch Bestandteil der Ressourcenbezeichner. Eine einzelne Ressource kann mehrere Bezeichner haben, sodass% ce_de% und /issues/ dieselbe Ressource haben können Ein einzelner Bezeichner kann nicht zu mehreren Ressourcen gehören, aber ich denke, das ist offensichtlich.) In diesem Fall müssen Sie keine Ressourcen für Schreiber und Redakteure erstellen, sondern nur eine einzige Ressource mit mehreren Bezeichnern (IRIs).