Читать книгу GraphQL - Dominik Kress - Страница 24

JSON:API ist eine JSON-basierte API-Spezifikation mit dem Ziel, API-Calls effizienter zu gestalten. Genau wie REST ist es eine Kombination aus HTTP und JSON sowie einer Definition von Regeln und Standards für die Kommunikation. JSON:API hat einfache Ressourcen, die über einen Call gegen den definierten Endpunkt des Service abgerufen werden können.

GET /articles HTTP/1.1

Accept: application/vnd.api+json

Listing 1–4 JSON API Get Request

Als Response liefert der Server ein JSON-Dokument. Das hat eine definierte, erwartbare Struktur. So hält es ein Relationship-Objekt, das sowohl Informationen über die Beziehung der Ressource zu anderen Ressourcen hält, als auch weitere, einfache Informationen zur Beziehung. Ruft man den Link innerhalb der angegebenen Relation auf, erhält man die Repräsentation der in Beziehung zu ihr stehenden Ressource – ähnlich dem HATEOS-Prinzip bei REST.

// ...

{

"type": "articles",

"id": "1",

"attributes": {

"title": "The Force for Beginners"

},

"relationships": {

"author": {

"links": {

"self": "http://example.com/articles/1/relationships/author",

"related": "http://example.com/articles/1/author"

},

"data": {

"type": "people",

"id": "9"

}}},

"links": {

"self": "http://example.com/articles/1"

}

} // ...

Listing 1–5 JSON API Get Response

Zusätzlich bietet JSON:API jedoch eine für das Verbinden verschiedener Ressourcen extrem nützliche Funktionalität: Compound Documents. Dabei handelt es sich um die Repräsentation einer Ressource, die eine in Relation stehende Ressource inkludiert.

Somit kann im oberen Beispiel die Repräsentation des Artikels durch die Informationen des verlinkten Autors erweitert werden; ohne dass man dabei den Roundtrip eines zweiten Requests auf einen verlinkten Endpunkt machen muss.

// ...

{

"data": [{

"type": "articles",

"id": "1",

"attributes": {

"title": "The Force for Beginners"

},

"links": {

"self": "http://example.com/articles/1"

},

"relationships": {

"author": {

"links": {

"self":

"http://example.com/articles/1/relationships/author",

"related": "http://example.com/articles/1/author"

},

"data": {

"type": "people",

"id": "9"

}

},

}

}],

"included": [{

"type": "people",

"id": "9",

"attributes": {

"first-name": "Obi-Wan",

"last-name": "Kenobi",

"profession": "Jedi-Master"

},

"links": {

"self": "http://example.com/people/9"

}

}],

} // ...

Listing 1–6 JSON API Compound Document

Dabei ist zu beachten: Das Relations-Objekt hält noch immer nur die ID des Autors, deren Repräsentation findet sich jedoch im included-Teil des Dokuments. Das ist wichtig, da bei multiplen Relationen auf dasselbe Objekt sonst eine hohe Redundanz entstehen würde. Generell kann man auch einfach im Request angeben, welche Relationen man in der Response inkludieren möchte. Dies gilt auch für eine Liste oder verschachtelte Ressourcenrelationen.

Ebenso kann die Repräsentation auf verschiedene Felder je Ressource verringert werden, um den Payload der Response noch weiter zu reduzieren. Solch ein flexibel gestalteter Request kann dann wie folgt aussehen:

GET /articles?include=author&fields[articles]=title,body

&fields[people]=name HTTP/1.1

Accept: application/vnd.api+json

Listing 1–7 JSON API Specified Request

Zudem bietet JSON:API noch die Möglichkeit für Paginierung, Sortierung und Filter im Request. Mit diesem Prinzip lässt sich also genau angeben, welche Ressource und deren Relationen in welcher Weise ausgegeben werden. Damit sind Ressourcen letztendlich nach ihren Relationen in Graphen abgebildet.

Auch für manipulative Funktionen wie das Erstellen, Ändern oder Löschen der Ressourcen kann man sich dieser Graphstruktur bedienen und mehrere Objekte in nur einem Request kaskadierend manipulieren. Man spart somit einige in klassischem REST sonst nötige Roundtrip-Requests.