Drupal 10 : Webservices REST API

Les services web sont un principe permettant à des applications de communiquer entre elles à distance, via Internet, et ceci indépendamment des plates-formes et des langages sur lesquelles elles reposent.

Il n'y a donc pas de différence fondamentale entre l'interaction d'un navigateur avec une ressource et celle d'un service web avec une ressource. Ce qui diffère se situe au niveau du format de la représentation des données renvoyées dans la réponse : HTML pour les navigateurs, XML ou JSON pour les services web.

Un point rapide sur HAL

HAL, ou encore Hypertext Application Language, est un format fournissant une manière simple et consistante de fournir des liens entres diverses ressources d’une API.

HAL permet de rendre les APIs plus facilement explorables et d’une certaine manière d’intégrer directement la documentation de l’API dans cette dernière. Elle peut fournir la manière d'interroger une ressource liée à la ressource actuellement interrogée au sein même de la réponse. Exemples : les liens vers les pages précédente et suivante dans le cadre d’une ressource qui liste des contenus ou encore le lien vers l’édition du profil de l’utilisateur lorsque l’on récupère son profil pour consultation.

REST et Drupal 10

Dans le cœur de Drupal 10, les interactions avec les entités de contenu sont supportées via une interface REST. Par défaut, les méthodes HTTP supportées sont GET, POST, PATCH et DELETE.

Le module REST est dépendant du module Serialisation qui fourni les représentations JSON et XML des entités. D’autres représentations sérialisées sont disponibles en activant le module JSON:API par exemple.

Le module REST de Drupal 10 ne possède aucune interface graphique. Les modifications et ajustements de configuration doivent s’effectuer directement en surchargeant les fichiers de configuration YAML de Drupal.

Récupération d’informations

L’opération la plus simple est la récupération des informations d’une entité.

Par défaut, l’ensemble des opérations sont disponibles sur les entités de contenu de type nœud, il est néanmoins possible de personnaliser ce comportement (par exemple, changer le format de sortie en JSON ou XML, ou encore rajouter une méthode d’authentification telle que oauth).

Pour ce faire, il faut tout d’abord exporter la configuration du module REST. La configuration de base devrait ressembler à ceci. (Configuration > Configuration synchronization  > Export > Single item)

# rest.settings.yml
# Example configuration for enabling REST resources.
resources:
  # Enable the node resource.
  'entity:node':
    GET:
      supported_formats:
        - hal_json
      supported_auth:
        - basic_auth
  # Enable the taxonomy term resource.
  'entity:taxonomy_term':
    GET:
      supported_formats:
        - hal_json
      supported_auth:
        - basic_auth

Des modifications peuvent alors être apportées en modifiant ce fichier YAML puis en important à nouveau cette configuration dans Drupal.

Exemple : pour autoriser le format de données XML, la configuration de la ressource node sur la méthode GET deviendrait :

  # rest.settings.yml
  # Enable the node resource.
  'entity:node':
    GET:
      supported_formats:
        - hal_json
        - xml

À noter qu’un module de la communauté existe afin de fournir une interface graphique pour réaliser ceci : REST UI

Exemple de mise en œuvre :

Après avoir créé un contenu, activez le module RESTFul Web Services ainsi que HAL

N’oubliez pas de configurer les permissions.

A présent, à l’aide d’un navigateur non connecté sur votre instance Drupal, rendez-vous à l’adresse http://moninstance.dev/node/1?_format=hal_json.

Voici un exemple ce que vous obtiendrez.

(Le contenu est volontairement tronqué dans cet exemple)

Création de contenu

Afin de pouvoir créer du contenu à l’aide des modules de webservices de Drupal 8 ou 9, il est impératif d’activer le module core HAL.

Comme il s’agit ici de création de contenu, cette opération va probablement devoir être sécurisée (seul un utilisateur possédant les droits de création de contenu doit être accepté). C’est pourquoi nous allons activer le module HTTP Basic Authentication qui fourni la méthode authentification “Basic” la plus simple.

Afin de créer un contenu, il convient de créer une requête sur l’adresse http://<site_drupal>/entity/<entity_type>.

Pour s’identifier, le client HTTP doit envoyer la requête en spécifiant l'en-tête HTTP « Authorization » et avec la valeur de connexion. Celle-ci est composée de la méthode utilisée (Basic) suivie de la représentation en Base64 du nom de l'utilisateur et du mot de passe séparés par le caractère « : » (deux-points).

Protection supplémentaire, il faut également fournir un en-tête HTTP « X-CSRF-Token ». Ce dernier est récupérable à l’adresse rest/session/token de votre site.

Il faut néanmoins rester vigilant car de nombreux contenus Drupal sont composés d’entités liées entres-elles. Par exemple, si l’on souhaite créer un commentaire, il faut pouvoir le lier à un utilisateur. Pour ce faire, il est nécessaire de renseigner ce lien grâce à l’entrée “ _links ” du JSON.

Afin de recréer ce lien, il est plus simple de tout d’abord effectuer un appel GET sur cette ressource et d’en étudier ses entrées “ _links ”.

Les entrées du tableau “ _links ” sont créées et normalisées par le module >HAL (voir premier paragraphe du chapitre).

Pour résumer

Requête

http://example.com/entity/node

Headers

Corps

{
 "_links": {
   "type": {
     "href": "http://example.com/rest/type/node/article"
   }
 },
 "title": {
   "value": "Test Article 2"
 },
 "type": {
   "target_id": "article"
 }
}

Mise à jour de contenu

Il est également possible de mettre à jour des contenus grâce au verbe HTTP PATCH .

Afin de pouvoir créer du contenu à l’aide des modules de webservices de Drupal 8 ou 9, il est impératif d’activer le module core HAL ainsi que HTTP Basic Authentication.

Afin de mettre à jour un contenu, il convient de créer une requête sur l’adresse http://<site_drupal>/node/<nid>.

À l’instar de la création de contenu, il est également nécessaire de passer les en-têtes HTTP « Authorization » et « X-CSRF-Token ».

Pour résumer

Requête

http://example.com/node/<nid>

Headers

Corps

{
 "_links": {
   "type": {
     "href": "http://example.com/rest/type/node/article"
   }
 },
 "nid": {
   "": {
     "value": "8"
   }
 },
 "type": {
   "target_id": "article"
 },
 "promote": {
   "value": "1"
 },
 "body": {
   "": {
     "value": "foo bar baz", "lang": "en"
  }
 }
} 

Suppression de contenu

A l'aide du verbe HTTP DELETE, il est bien sur possible de supprimer des entités. Le fonctionnement presque identique au méthodes précédentes.

Requête

https://example.com/node/<nid>

Headers