JSON:API backend

JsonDrop API utilise l’implémentation JSON:API pour l’interaction backend/frontend et une implémentation totalement conforme à la :

Spécification JSON:API

Collection Postman avec des points de terminaison prêts à l’emploi :

https://drive.google.com/file/d/1rMf0XdrK1zXwPqLQVsTH44Z2ttFxj7ss/view?usp=drive_link

Selon ses propres termes, la spécification JSON:API est :

[Une] spécification sur la manière dont un client doit demander que des ressources soient récupérées ou modifiées, et comment un serveur doit répondre à ces requêtes.

JSON:API est conçu pour minimiser à la fois le nombre de requêtes et la quantité de données transmises entre clients et serveurs. Cette efficacité est obtenue sans compromettre la lisibilité, la flexibilité ou la découvrabilité.

Les structures de données de Drupal, c’est-à-dire les types d’entités, bundles et champs, sont extrêmement bien adaptées à JSON:API.

En activant le module JSON:API, vous obtenez immédiatement une API REST complète pour chaque type dans votre application Drupal. JSON:API inspecte vos types d’entités et bundles afin de fournir dynamiquement des URLs pour accéder à chacun d’eux en utilisant les méthodes HTTP standard, GET, POST, PATCH et DELETE.

JSON:API adopte la philosophie que le module doit être prêt pour la production « prêt à l’emploi ». Cela signifie que le module est très orienté sur l’endroit où résideront vos ressources, quelles méthodes sont immédiatement disponibles dessus, et laisse le contrôle d’accès au système de permissions du noyau Drupal. À l’heure actuelle, il n’existe aucune page de configuration disponible. Cela signifie que vous pouvez démarrer rapidement avec une application Drupal pilotée par API avec un minimum d’effort.

Les pages enfants de cette documentation incluront :

• Concepts fondamentaux de la spécification JSON:API — et comment ils s’appliquent à Drupal
• Une vue d’ensemble large de l’API que le module met à disposition.
• Des informations pratiques sur la manière de composer vos requêtes HTTP.
• Comment authentifier vos requêtes.
• Les pièges courants.
• Documentation spécifique pour :
  • Récupération de ressources individuelles (GET)
  • Récupération de collections de ressources (GET avec filtres, pagination, et tri)
  • Création de nouvelles ressources (POST)
  • Mise à jour de ressources existantes (PATCH)
  • Suppression de ressources existantes (DELETE)

Si vous avez des questions spécifiques, veuillez créer une demande d’assistance dans la file d’attente des problèmes du module JSON:API [480 issues].

L’API que le module JSON:API met à disposition est centrée sur les types d’entités et bundles de Drupal. Chaque bundle reçoit son propre chemin URL unique, qui suit tous un schéma commun.

Contrairement au module REST du noyau Drupal, ces chemins ne sont pas configurables et sont tous activés par défaut. Contrairement au REST du noyau, JSON:API n’est pas simplement un format comme JSON ou HAL+JSON. Il englobe un ensemble beaucoup plus large de règles sur la façon dont votre API fonctionnera. Il dicte quelles méthodes HTTP doivent être utilisées, quels codes de réponse HTTP doivent être renvoyés dans des circonstances spécifiques, le format de votre corps de réponse, et le lien entre les ressources. Pour une comparaison plus détaillée, voir JSON:API vs. le module REST du noyau.

Types

Chaque ressource dans JSON:API doit avoir une propriété type globalement unique. L’implémentation JSON:API de Drupal dérive cette propriété type du nom machine du type d’entité et du nom machine du bundle. Par exemple, articles, pages et utilisateurs reçoivent respectivement les types node--article, node--pages, et user--user. Notez que le type d’entité utilisateur dans Drupal n’a pas de bundle. Lorsqu’un type d’entité n’a pas de bundle, le type d’entité est simplement répété pour la cohérence.

Structure de l’URL

Une URL JSON:API ressemble à ceci :

GET|POST     /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}

Chaque type de ressource doit être adressable de façon unique dans l’API. Cela signifie que chaque type disponible dans l’API doit avoir une URL unique. En plus de cela, cela signifie qu’une URL donnée ne peut récupérer qu’un seul type de ressource. L’implémentation Drupal suit le modèle : /jsonapi/{entity_type_id}/{bundle_id}[/{entity_uuid}].

L’URL est toujours préfixée par /jsonapi.

Après cela, l’identifiant du type d’entité et l’identifiant du bundle sont concaténés par une barre oblique. Notez qu’il n’existe pas d’URL à /jsonapi/node, car cette URL violerait la spécification en servant plusieurs types de ressources (en raison de multiples types de bundles) depuis une seule URL.

Existe :
/jsonapi/node/page
/jsonapi/node/article

N’existe pas :
/jsonapi/node

Après l’identifiant du type d’entité et du bundle, il y a une partie d’identification optionnelle. Pour adresser une ressource unique, que ce soit pour la récupérer, la mettre à jour ou la supprimer, vous devez inclure cette partie dans le chemin. C’est toujours l’UUID de la ressource. Lors de la création d’une nouvelle ressource, avec ou sans ID, ou lors de la récupération d’une collection de ressources d’un seul type, on omet cette partie d’identification.

GET, POST
/jsonapi/node/article

PATCH, DELETE
/jsonapi/node/article/{uuid}

Méthodes HTTP

JSON:API spécifie quelles méthodes HTTP accepter. Ce sont : GET, POST, PATCH, et DELETE. Notamment, PUT n’est pas inclus.

• GET – Récupérer des données, peut être une collection de ressources ou une ressource individuelle
• POST – Créer une nouvelle ressource
• PATCH – Mettre à jour une ressource existante
• DELETE – Supprimer une ressource existante

En-têtes de requête

Assurez-vous d’utiliser les en-têtes « Content-Type » et « Accept » quand cela est approprié. Voir Responsabilité du client pour plus de détails.

Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

Codes de réponse

La spécification JSON:API dicte aussi les réponses acceptables. L’implémentation Drupal utilise un sous-ensemble de celles-ci. Le module peut répondre avec les codes suivants :

• 200 OK – Toutes les requêtes GET et PATCH réussies
• 201 Created – Toutes les requêtes POST réussies (la réponse inclut la ressource nouvellement créée)
• 204 No Content – Toutes les requêtes DELETE réussies

Article extrait de la documentation Drupal.