HAL + JSON-Hypermedientyp kein Medientyp für REST?

Question

Kann der Hypermedia-Typ HAL + JSON so verwendet werden, dass ein REST-fähiger Dienst erstellt wird?

Von dem, was ich gelesen habe, sollte der Client einer RESTful-API nicht verschiedene Ressourcen mit speziellen Fällen behandeln müssen. Der Medientyp sollte stattdessen verwendet werden, um zu beschreiben, wie Ressourcen aussehen sollen.

Die HAL spec gibt folgendes Beispiel:

GET /orders 

{ 
    ... 
    "shippedToday": 20, 
    ... 
} 

`` `

Als Kunde von dieser Probe HAL + API JSON-Serving, scheine ich, dass eine "Ordnung" zu müssen wissen, hat eine Attribut von shippedToday. Das scheint gegen die Einschränkung zu gehen, dass der Client die Syntax der Repräsentation nicht verstehen sollte.

Dies ist keine Kritik an HAL. Die Frage ist, meinem (und anderen) Verständnis des RESTful-API-Designs zu helfen.

Answer 1

Kann der Hypermedia-Typ HAL + JSON so verwendet werden, dass ein RESTful-Service erstellt wird?

Ja, definitiv.

Die API sollte eine Billboard-URL haben, die in Ihrem Fall / sein könnte.

Dies ist der Einstiegspunkt, von dem Menschen und idealerweise sogar Maschinen beginnen können, Ihre API zu entdecken.

Nach der HAL specification einer Ressourcen-Darstellung enthält eine optionale Eigenschaft "_links" genannt, die hier beschrieben wird:

Es ist ein Objekt, dessen Eigenschaftsnamen Link Beziehungstypen sind (wie durch RFC5988 definiert) und Werte sind entweder ein Link-Objekt oder ein Array von Link-Objekten.

Diese Hyperlinks repräsentieren also den Hypermedienteil Ihrer API. Die Beziehungen können IANA -registrierte Beziehungen sein oder Sie können Ihre eigenen Erweiterungsbeziehungen verwenden.

Beziehungen sollten nicht mehrdeutig sein. Ihre Namen sollten eindeutig sein. Aus diesem Grund wird empfohlen, URIs aus Ihrer eigenen Domäne als Namen für Ihre eigenen Beziehungen zu verwenden. Diese URIs identifizieren eine Ressource, die die Beziehung darstellt, und enthalten eine API-Dokumentation, eine von Menschen oder Maschinen lesbare Dokumentation Ihrer Beziehung.

In Ihrem Fall wäre dies eine Relation, die den Statusübergang zur Ressource /orders beschreibt. Dies sollte auch eine Beschreibung und Erläuterung der Antwort enthalten und daher dokumentieren, dass z. Die Ressource /orders stellt eine Liste von Aufträgen dar und hat eine Eigenschaft namens "shippedToday" mit einem Wert der Typnummer. Hier

ist ein Beispiel für eine Antwort GET/HTTP/1.1 Anfrage:

HTTP/1.1 200 OK 
Content-Type: application/hal+json 

{ 
    "_links": { 
     "self": { "href": "/" }, 
     "http://yourdomain.com/docs/rels/orders": { "href": "/orders" }, 
    } 
} 

Unter http://yourdomain.com/docs/rels/orders sollte die API-Dokumentation sein.