Drupal 10 : Webservices REST API

Exposer une API REST grâce à Drupal.

Cet article a été initialement rédigé pour Drupal 8 mais son contenu est toujours d'actualité pour Drupal 9 et Drupal 10.

N'hésitez pas à nous contacter ou à vous inscrire à notre formation «Drupal pour les développeurs et développeuses» pour en savoir plus !

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.

HAL a été retiré du cœur

Depuis Drupal 9.4.0, le module HAL a été marqué comme déprécié et déplacé comme un module contrib. Il est maintenant remplacé par le module JSON:API qui permet de faire la même chose mais avec plus de fonctionnalités.

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.

Tableau de permissions illustrant la permission "access patch on Content resource" cochée.

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.

Capture d'écran d'un objet JSON dont les attributs sont ouvrables/fermables et la majorité sont refermés. Ex d'attributs : created, status, sticky...

(Le contenu est volontairement tronqué dans cet exemple)

Création de contenu

Attention, avec Drupal 10, il faut utiliser le module JSON:API pour exposer les points d'entrée de l'API. Son fonctionnement est différent du module REST.

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

Nom de l’en-tête

Valeur de l’en-tête

X-CSRF-Token

(récupéré via rest/session/token)

Authorization

Basic (Hash base 64 username/password)

Content-Type

application/hal+json

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

Nom de l’en-tête

Valeur de l’en-tête

X-CSRF-Token

(récupéré via rest/session/token)

Authorization

Basic (Hash base 64 username/password)

Content-Type

application/hal+json

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

Nom de l’en-tête

Valeur de l’en-tête

X-CSRF-Token

(récupéré via rest/session/token)

Authorization

Basic (Hash base 64 username/password)

Commentaires

DamienGR Lundi 2 mai 2016 - 13:28
Merci pour cet article. Petite erreur de frappe : A présent, à l’aide d’un navigateur non connecté sur votre instance Drupal, rendez-vous agrave; l’adresse “ http://...
En réponse à par CMS NOOBIE
DuaelFr Mardi 29 janvier 2019 - 10:18

C'est relativement facile.

Une fois le module RESTful Web Services activé, il est possible de créer un nouvel affichage (display) de type "Export REST" dans Views. Une fois configuré avec une URL dédiée, par exemple /rest/node, il suffit d'accéder à l'URL https://example.com/rest/node?_format=json et tu verras le contenu de ta vue.

Robert Lundi 22 juin 2020 - 13:48

Bonjour et merci beaucoup pour ce billet très clair.

Je rencontre une difficulté pour faire ceci : une simple lecture GET mais avec authentification.

- Créé une Views avec display REST EXPORT -> affichage OK dans mon client HTTP

- J'ajoute "basic auth" et comme rôle permis : utilisateur anonyme -> affichage OK dans mon client HTTP

- Je remplace le rôle par "utilisateur authentifié".
Dans mon client HTTP, je renseigne les champs "authorization" avec mon login:pass base64 encodé, le content-type, et le X-CSRF-Token  -> je me heurte à une redirection en boucle vers /user/login/?prev_path=/user/login/

Est-ce que ça vous parle ? Merci d'avance



 

Votre commentaire

Le contenu de ce champ sera maintenu privé et ne sera pas affiché publiquement.
Votre adresse servira à afficher un Gravatar et à vous notifier des réponses. Votre commentaire sera anonymisé si ce billet est dépublié pendant plus de 3 mois.
Pour lutter contre le spam notre système enregistre votre adresse IP et votre adresse e-mail si vous la partagez.
Nous vous invitons à consulter notre politique de confidentialité pour comprendre les traitements faits de ces données et comment les rectifier.

À propos de Nicolas

Co-fondateur - Expert technique

Je découvre Drupal en 2007 alors que j'occupe le poste d’Adjoint de Production du département Multimédia au sein du Service d'Information du Gouvernement. Je fus chargé de la réalisation de la nouvelle version, encore en ligne à ce jour, du site du Premier ministre.