Drupal 8 : Webservices REST

Cet article est extrait de notre formation drupal 8 "de Drupal 7 à Drupal 8" à destination des développeurs. N'hésitez pas à nous contacter 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é 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 8

Dans le cœur de Drupal 8, 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 HAL par exemple.

Le module REST de Drupal 8 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 par exemple).

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 : RestUI

Exemple de mise en oeuvre :

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://d8.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, 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êtes 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, 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.

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.

À propos de Julien

Gérant - Co-fondateur - Scrum master & Expert technique

Utilisateur de Drupal depuis 2008, j’ai fait mes armes comme développeur chez Commerce Guys puis me suis mis à encadrer les nouveaux arrivants avant de donner des formations, participer aux avant ventes et accompagner les équipes au passage à Scrum.

Je suis impliqué dans la communauté française de Drupal depuis 2009, j’ai été tour à tour président puis vice-président de l’association Drupal France et francophonie entre 2011 et 2013.