HATEOAS POST-Link in HAL

Question

Wie beschreibe ich POST-Links in HAL?

Ich bin ein RESTful API mit HATEOAS Constraints, ähnlich wie Wikipedia's HATEOAS example Gestaltung aber in HAL JSON (dropping das Schema, Host usw. aus Gründen der Klarheit) ausgedrückt:

GET /accounts/12345 

{ 
    "id" : 12345, 
    "balance" : 100.00 
    "_links" : { 
    "self" : { 
     "href" : "/accounts/12345" 
    }, 
    "transfer" : { 
     "href" : "/accounts/12345/transfer{?amount,target}", 
     "templated" : true 
    } 
    } 
} 

den "Transfer" Aktion auszuführen der Kunde würde, vermutlich tun:

GET /accounts/12345/transfer?amount=100.00,target=54321 

{ 
    "id" : 34567, 
    "amount" : 100.00 
    "_links" : { 
    "self" : { 
     "href" : "/transfers/34567" 
    }, 
    "source" : { 
     "href" : "/account/12345" 
    }, 
    "target" : { 
     "href" : "/account/54321" 
    } 
    } 
} 

den "Transfer" Link per GET erstellt eine neue Ressource in "Transfers" Aufrufe. Aber ein GET zu tun, um eine neue Ressource zu erstellen, ist nicht idempotent und es fühlt sich falsch an; eine RESTful Ressource zentrierten API würde POST:

POST {amount: 10.00, source: 12345, target: 54321} /transfers/ 

{ 
    "id" : 34567, 
    "amount" : 100.00 
    "_links" : { 
    "self" : { 
     "href" : "/transfers/34567" 
    }, 
    "source" : { 
     "href" : "/account/12345" 
    }, 
    "target" : { 
     "href" : "/account/54321" 
    } 
    } 
} 

Aber wie beschreibe ich dieses POST und die erforderlichen Formelemente in HAL so kann der Kunde die „Richtige“ ohne einfach nicht hart codiert? Vielleicht so etwas wie:

{ 
    "id" : 12345, 
    "balance" : 100.00 
    "_links" : { 
    "self" : { 
     "href" : "/accounts/12345" 
    }, 
    "transfer" : { 
     "href" : "/transfers{?amount,source,target}", 
     "templated" : true, 
     "method" : "POST" 
    } 
    } 
} 

Aber method nicht Teil der HAL specification und es gibt keine analoge Kennung - so fühlt es sich wie ich auf dem Holzweg bin ...

Vielleicht sollte mein Kunde nur „wissen "Ein GET von transfer gibt übereinstimmende Übertragungsressourcen zurück, und ein POST an transfer erstellt eine neue Übertragungsressource.

FWIW, verwendet meine Implementierung Frühlings-Boot 2 mit Feder HATEOAS so die Folgefrage ist, wie dies mit Frühling HATEOAS ...

Answer 1

Sie nicht tun können, um auszudrücken, dass mit HAL. Mike Kelly, der Schöpfer von HAL, states on GitHub

Der „HAL Weg“, dies zu tun ist, um die link rel Dokumentation zu verwenden, um die zur Verfügung stehenden Methoden in einer für Menschen lesbare Form zu vermitteln. dh. Ihr bellt Beispiel wie folgt aus (man beachte die „bellt“ link rel ist jetzt eine URL)

{ 
    "_links": { 
     "http://docs.example.com/barks": { "href": "/v1/dogs/1/barks" } 
    } 
} 

und wenn ein Entwickler ruft die URL http://docs.example.com/barks in einem Browser aussehen würde, die Dokumentation, die zur Verfügung stehenden Methoden, gültige Anforderung Körper angeben , mögliche Antwortcodes, Antwortgremien, usw. Der Entwickler wird dies dann in den Klienten kodifizieren, den sie baut.

Dies ist ein großer Fehler der HAL spec imho, aber es gibt andere mediatypes, die dieses Problem angehen, wie Mason oder die HAL Erweiterung HAL-FORMS. Es könnte sich lohnen, diese zu überprüfen, obwohl ich nicht sicher bin, wie sie sich in Spring integrieren.