Inclusions

En Bref : Utilisez une chaîne de requête comme ?include=field_comments.uid pour inclure toutes les entités référencées par field_comments ainsi que toutes les entités référencées par uid sur ces entités !

JSON:API vous aide à réduire le nombre de requêtes HTTP en vous permettant de spécifier les chemins de relations que vous souhaitez inclure dans le document de réponse. Comment ?

Récupération de ressources individuelles

Récupérer un article

Imaginons que vous avez un article avec deux commentaires et que chacun de ces commentaires a le même auteur. Pour obtenir toutes ces données sans inclure, vous feriez d’abord une requête GET /jsonapi/node/article/some-random-uuid :

{
  "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"
          }
        }
      }
    }
  }
}

Récupérer un commentaire

Puis, vous feriez une requête à GET /node/article/some-random-uuid/field_comments :

{
  "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"
          }
        }
      }
    }
  }]
}

Récupérer les utilisateurs

Et encore, vous devrez faire deux autres requêtes à /comment/one-random-uuid/uid et /comment/two-random-uuid/uid. Nous voyons que la deuxième requête est totalement inutile car l’auteur des deux commentaires est le même dans cet exemple.

Alors, comment les inclusions peuvent-elles aider ?

Récupérer tout en une seule fois avec include

C’est simple ! Il suffit d’ajouter un paramètre de requête à l’URL initiale avec les noms des champs de relation que vous souhaitez inclure, et le serveur saura tout chercher pour vous et l’ajouter au document de réponse original.

Dans notre exemple, la requête URL serait GET /jsonapi/node/article/some-random-uuid?include=field_comments.uid. En d’autres termes, vous demandez « merci d’ajouter les objets ressource pour le champ field_comments de l’article, puis aussi les objets ressource pour le champ uid sur les commentaires référencés ». Ces « chemins de relations » peuvent être aussi longs que vous voulez, il n’y a pas de limite !

Le document de réponse que vous recevrez du serveur serait :

{
  "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": "two-random-uuid",
    "relationships": {
      "uid": {
        "data": [{
          "type": "user",
          "id": "another-random-uuid"
        }],
        "links": {
          "related": {
            "href": "https://my.example.com/comment/two-random-uuid/uid"
          }
        }
      }
    }
  }, {
    "type": "user",
    "id": "another-random-uuid",
    "attributes": {
      "name": "c0wb0yC0d3r"
    }
  }]
}

Plutôt cool, non ? Nous avons toutes les données en une seule requête ! Notez que l’objet ressource utilisateur n’est inclus qu’une seule fois, même s’il est référencé deux fois. Cela réduit la taille de la réponse. Notez également la présence d’une clé data dans chaque objet relation. Cela vous permet de corréler les objets ressource inclus avec ceux qui les ont référencés.

Quand utiliser include ?

Concernant la taille de la réponse... dans cet exemple, nous avons gagné du temps en obtenant toutes les ressources en une seule requête. Cependant, dans certaines circonstances, inclure des objets ressource liés peut augmenter considérablement la taille de la réponse et/ou ralentir le temps jusqu’au premier octet. Dans ce cas, il peut être préférable de faire plusieurs requêtes en parallèle.

Include pour collection et relation

Enfin, le paramètre de requête include est aussi supporté sur les ressources de collection et de relation ! Les inclusions sur les collections peuvent vous faire économiser beaucoup plus de requêtes.

Exemple d’include pour une collection

Une récupération avec inclusions pour une collection peut ressembler à GET /jsonapi/node/article?include=uid. Les included sont similaires, séparés des data (tableau au lieu d’objet) comme montré ci-dessous.

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

Article extrait de la documentation Drupal.