Glossaire des termes

TL;DR :

• Les requêtes HTTP sont faites vers des ressources JSON:API. Ne les confondez pas avec des objets de ressource.
• L’objet JSON que le client reçoit s’appelle un document.
• Un document est toujours un objet JSON et contient des données principales sous une clé data.
• Les données sous cette clé sont appelées objets ressource ou objets identifiants de ressource.
• Lorsque vous demandez que des données liées soient incluses dans le document, cela devient un document composé.
• Un document composé est un document contenant une clé included dans l’objet de niveau supérieur.
• Les ressources retournant plusieurs objets ressource sont appelées ressources de collection.
• Les ressources retournant un seul objet ressource sont appelées ressources individuelles.
• Les ressources retournant des informations sur les relations entre objets ressource sont appelées ressources de relation.
• En termes Drupal :
  • Objets ressource → Entités
  • Objets identifiants de ressource → Éléments de champ référence d’entité
  • Document → Charge utile JSON de la requête/réponse

Ce qui suit fournit une brève description des termes et concepts utilisés pour décrire le module JSON:API.

Ce glossaire ressemble étroitement à la spécification JSON:API, mais tente de cadrer les définitions telles qu’elles s’appliquent à Drupal. Il développe aussi des subtilités de la spécification qui peuvent ne pas être évidentes pour un débutant qui ne connaît pas intimement la spécification ou comment lire une spécification.

Beaucoup de ces définitions sont interdépendantes. Il existe un schéma en bas de cette page qui place ces termes dans leur contexte.

Ressource

Un emplacement où un document de réponse JSON:API peut être récupéré. Une ressource est accessible via son URL (localisateur uniforme de ressource). Elle ne doit pas être confondue avec un "objet ressource". Une ressource n’a pas de correspondance un-à-un avec les données d’une application.

En termes Drupal, cela signifie qu’une ressource JSON:API n’est pas synonyme d’une entité. Une ressource est plutôt un endroit où l’on peut récupérer les données d’un concept. Par exemple, ce concept peut être « une collection d’objets ressource du type node--article » ou « une représentation du champ référence d’entité field_tags d’un nœud article particulier ».

Document de réponse

Le corps encodé en JSON retourné par une ressource JSON:API. C’est l’enveloppe dans laquelle les données ou erreurs sont communiquées au client HTTP. On l’appelle parfois objet de niveau supérieur. Lorsqu’un document contient un membre included, il est appelé document composé.

Document composé

Un document de réponse contenant un membre included. Un document composé peut être utilisé pour éliminer des requêtes HTTP en intégrant des objets ressource liés avec les données principales d’une réponse. On peut demander un document composé en ajoutant un paramètre de requête include à l’URL de la requête.

Document d’erreur

Un document de réponse contenant un membre errors qui contient un ou plusieurs objets d’erreur. Il ne contiendra jamais un membre data. Le code HTTP d’une réponse contenant un document d’erreur sera toujours un code 4xx ou 5xx.

Ressource individuelle

Une ressource qui contient un seul objet ressource comme membre data du document de réponse. Avec une autorisation suffisante, cette ressource est lisible et modifiable. En termes Drupal, cette ressource sert à « voir », « mettre à jour » ou « supprimer » une entité individuelle. Elle ne peut pas servir à créer une entité.

Ressource de collection

Une ressource qui contient plusieurs objets ressource comme membre data du document de réponse. Avec une autorisation suffisante, cette ressource est lisible et modifiable. Ces ressources peuvent être paginées, filtrées et triées. En termes Drupal, cette ressource peut être utilisée pour « créer » une nouvelle entité. Elle ne peut pas être utilisée pour « mettre à jour » ou « supprimer » des entités dans la collection.

Ressource de relation

Une ressource qui contient un objet de relation comme objet de niveau supérieur du document de réponse. Elle contient un ou plusieurs objets identifiants de ressource qui représentent chacun une référence d’un objet ressource vers un autre. Avec une autorisation suffisante, cette ressource est lisible et modifiable. En termes Drupal, cette ressource peut être utilisée pour « voir » ou « éditer » les éléments d’un champ référence d’entité unique.

Ressource liée

Une ressource qui est une ressource de collection spéciale contenant un ou plusieurs objets ressource comme membre data du document de réponse. Les objets ressource dans cette collection sont les sujets d’une relation sur un objet ressource référent. Cette ressource est en lecture seule. En termes Drupal, cette ressource peut être utilisée pour « voir » les entités qui sont référencées par un champ référence d’entité, mais ne peut pas être utilisée pour « mettre à jour » ces entités ou pour « éditer » le champ référence d’entité qui les référence.

Membre du document

Un objet JSON qui fait partie du document JSON:API de niveau supérieur. Ces objets sont toujours situés dans le document sous des clés définies par la spécification (par exemple jsonapi, data, included ou errors).

Objet ressource

Une représentation d’une entité sous forme d’objet JSON. Il ne faut pas le confondre avec une "ressource". Il correspond un-à-un aux données de l’application.

Objet attributs

Un objet JSON représentant les informations sur l’objet ressource dans lequel il est défini. Les attributs peuvent contenir toute valeur JSON valide. En termes Drupal, cet objet représente toutes les valeurs des champs d’entité qui ne sont pas des références d’entité.

Objet relations (pluriel)

Un objet JSON contenant les références de l’objet ressource dans lequel il est défini vers d’autres objets ressource. Il contient de nombreux membres qui sont des objets relation (singulier). En termes Drupal, cet objet représente toutes les valeurs des champs référence d’entité.

Objet relation (singulier)

Un objet JSON représentant les références de l’objet ressource dans lequel il est défini vers d’autres objets ressource. Il contient des objets identifiants de ressource, chacun représentant une relation unique vers un autre objet ressource. En termes Drupal, cet objet représente un seul champ référence d’entité.

Objet identifiant de ressource

Un objet JSON très simple représentant une relation d’un objet ressource à un autre. Il ne faut pas le confondre avec un "objet ressource". Il contient uniquement une clé type et une clé id, et une clé optionnelle meta pour contenir des informations sur cette relation. Notamment, il ne contient pas de membre links.

Il fournit une "liaison de ressource" qui, dans un document composé, permet au client HTTP de faire le lien entre des objets relation et les objets ressource référencés dans le membre included d’un document composé.

Objet liens

Un objet JSON contenant des hyperliens vers d’autres ressources.

Objet erreur

Un objet JSON représentant une erreur survenue lors du traitement d’une requête. Il peut représenter des erreurs client, des erreurs de validation ou des erreurs serveur, entre autres.

Article tiré de la Documentation Drupal.