Enthält

TL;DR: Verwenden Sie einen Query-String wie ?include=field_comments.uid, um alle von field_comments referenzierten Entitäten und alle von uid auf diesen Entitäten referenzierten Entitäten einzuschließen!

JSON:API hilft Ihnen, HTTP-Anfragen zu reduzieren, indem Sie Beziehungs-Pfade angeben können, die Sie im Antwort-Dokument enthalten möchten. Wie?

Einzelne Ressourcen abrufen

Artikel abrufen

Nehmen wir an, Sie haben einen Artikel mit zwei Kommentaren und jeder dieser Kommentare hat den gleichen Autor. Um all diese Daten ohne Includes zu erhalten, würden Sie zuerst eine Anfrage an GET /jsonapi/node/article/some-random-uuid stellen:

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  }
}

Kommentar abrufen

Dann würden Sie eine Anfrage an GET /node/article/some-random-uuid/field_comments stellen:

{
  "data": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "two-random-uuid",
    "relationships": {
      "uid": {
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }
}

Benutzer abrufen

Und dann müssten Sie noch zwei weitere Anfragen an /comment/one-random-uuid/uid und /comment/two-random-uuid/uid stellen. Wir sehen, dass die zweite Anfrage eigentlich überflüssig ist, weil wir wissen, dass der Autor beider Kommentare im Beispiel der gleiche ist.

Wie können also Includes helfen?

Alles auf einmal mit Include abrufen

Es ist einfach! Indem Sie einfach einen Query-Parameter zur ursprünglichen Anfrage-URL mit den Namen der Beziehungfelder, die Sie einbeziehen möchten, hinzufügen, weiß der Server, dass er alles für Sie nachschlagen und dem ursprünglichen Antwort-Dokument hinzufügen soll.

In unserem Beispiel wäre die URL-Anfrage GET /jsonapi/node/article/some-random-uuid?include=field_comments.uid. Anders ausgedrückt sagen Sie: "Bitte füge die Ressourcenobjekte für das field_comments-Feld am Artikel hinzu, dann auch die Ressourcenobjekte für das uid-Feld bei den referenzierten Kommentaren." Diese "Beziehungspfade" können so lang sein, wie Sie möchten – es gibt kein Limit!

Das Antwortdokument, das Sie vom Server erhalten würden, sieht folgendermaßen aus:

{
  "data": {
    "type": "node--article",
    "id": "some-random-uuid",
    "relationships": {
      "field_comments": {
        "data": [{
          "type": "comment",
          "id": "one-random-uuid",
        }, {
          "type": "comment",
          "id": "two-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/node/article/some-random-uuid/field_comments"
          }
        }
      }
    }
  },
  "included": [{
    "type": "comment",
    "id": "one-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "another-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/one-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "comment",
    "id": "another-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "one-random-uuid",
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

Ist das nicht cool? Wir haben alle Daten mit einer einzigen Anfrage bekommen! Beachten Sie, dass das Benutzer-Ressourcenobjekt nur einmal enthalten ist, auch wenn es zweimal referenziert wird. Das hält die Antwort klein. Beachten Sie auch, dass es jetzt einen data-Schlüssel in jedem Beziehungsobjekt gibt. Damit können Sie die eingeschlossenen Ressourcenobjekte mit den referenzierenden Ressourcenobjekten korrelieren.

Wann sollte man Include verwenden?

Wenn wir schon von Antwortgröße sprechen ... In diesem Beispiel haben wir uns Zeit gespart, indem wir alle Ressourcen mit einer einzigen Anfrage bekommen haben. Unter bestimmten Umständen kann das Einbeziehen verwandter Ressourcenobjekte die Antwortgröße jedoch stark vergrößern und/oder die Zeit bis zum ersten Byte sehr langsam machen. In diesem Fall ist es eventuell besser, mehrere Anfragen parallel zu stellen.

Include für Sammlungen und Beziehungen

Der include-Query-Parameter wird auch bei Sammlungsressourcen und Beziehungsressourcen unterstützt! Includes bei Sammlungen können Ihnen viele weitere Anfragen ersparen.

Include-Beispiel für eine Sammlung

Includes für Sammlungen könnten so aussehen: GET /jsonapi/node/article?include=uid. Die included sind ähnlich wie zuvor vom data getrennt (Array statt Objekt), wie unten gezeigt.

{
  "data": [{...}],
  "included": [{
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

Artikel aus der Drupal Dokumentation.