Formation « Développer un thème WordPress sur mesure »

L’API REST de WordPress

Lecture : 8 minutes • 0

WordPress dispose depuis quelques années d’une API REST qui lui permet de communiquer facilement avec d’autres sites et applications. Dans ce cours on va voir ce qu’est une API REST, comment la manipuler ainsi que les usages les plus fréquents.

Qu’est-ce qu’une API REST ?

Dans le web d’aujourd’hui, les sites et applications ne peuvent plus faire bande à part : ils ont besoin de transmettre facilement leurs données, en lecture ou en écriture. C’est justement le but des API REST.

API REST

Définition

Une API Rest est une norme permettant à deux systèmes logiciels de communiquer entre eux et échanger des données sous forme de requêtes HTTP, via des URL. Les données sont généralement transmises au format JSON, le successeur du XML. En utilisant le protocole web standard, les API fonctionnent peu importe le langage utilisé par l’application : elles sont agnostiques de la technologie. Une application Java peut donc communiquer avec une application C#, sans souci.

Concrètement, une API utilise le web (HTTP) comme protocole de référence pour communiquer, et grâce à des standards prédéfinis, tout système pourra communiquer de la même manière. Et on va justement voir comment ça marche juste après.

Une fois que vous savez utiliser une API, vous savez toutes les utiliser !

Le saviez-vous ?

REST veut dire Representational State Transfer. Une API Rest est une api dont les normes sont standardisées, ce qui les rend plus simples à comprendre et manipuler.

Exemple d’API sur un site e-commerce

Si vous construisez un site e-commerce (avec WooCommerce notamment), il se peut que votre client vous demande d’interfacer votre site avec son logiciel de comptabilité, ou de gestion des stocks.

Schéma montrant un site qui communique avec un logiciel de comptabilité et de stocks
Grâce aux API Rest, les applications peuvent communiquer

À chaque commande, le site va envoyer à l’API du logiciel de compta les données de la vente. De son côté, le logiciel de gestion des stocks va envoyer au site le nombre de produits disponibles après un réapprovisionnement. Ce dernier pourrait tout aussi bien lire les stocks du sites, dans le but de faire un inventaire.

Conseil

Chaque application communique donc directement avec l’API REST du destinataire.

Avec cet exemple, vous comprenez l’importance d’avoir des données cohérentes et toujours à jour entre les différents acteurs de la boutique en ligne.

Applications web modernes et API REST

Aujourd’hui on utilise même des API REST pour des applications web modernes : au lieu que le serveur renvoie des pages HTML, il ne renvoie que des données brutes, et c’est Javascript (via des librairies comme Angular, Vue ou React) qui s’occupent de récupérer les données et générer l’interface correspondante (en HTML toujours).

Pour un site WordPress, cela veut dire que vous pourriez utiliser l’API pour créer un thème tout en JS (c’est ce qu’il est possible de faire avec Gatsby). Et vous pourriez également créer une application mobile native iOS ou Android qui se connecte à l’API du site pour récupérer les données.

D’ailleurs Netflix possède plus de 700 API qui communiquent entre elles pour vous fournir le service que vous connaissez.

Bien entendu, le but n’est pas d’aller forcément aussi loin ! Une simple lecture d’une API pour récupérer une donnée est bien souvent suffisante pour répondre aux principaux besoins.

Principe de fonctionnement d’une API

On a vu qu’une API fonctionne via le protocole web. Du coup, cela veut dire que les requêtes se feront en HTTPS, sous forme d’URL ! Et oui, exactement comme quand on navigue sur un site, sauf que c’est sur une URL spéciale, et que les données ne sont pas renvoyées en HTML, mais en JSON (données brutes).

Logique après tout, pourquoi inventer un nouveau protocole, alors que celui-ci fait le travail à merveille ?

Chaque URL, qu’on appellera du coup route, va représenter une ressource différente. Les ressources, ce sont les entités qu’on va pouvoir lire / écrire. Pour un site WordPress ce seront les pages, les articles, les catégories, les utilisateurs…

Il existe des API que l’on peut tester et utiliser sur Internet, comme la StarWars API ou encore la PokéAPI.

Exemple d'une route URL vers une API Rest distante
C’est l’URL qui indique ce que l’on veut récupérer

Prenons l’exemple de cette dernière, voici quelques routes :

Shell

On remarque une URL commune, qui est la base de l’API REST. C’est ici que tout commence : /api/v2/. Les API évoluant avec le temps, il est commun d’avoir un numéro de version.

Comme ça, le jour ou l’API évolue en profondeur, elle répondra sur une nouvelle URL (/v3/) et de cette manière cela ne cassera pas l’application des utilisateurs de la V2.

On indique ensuite la ressource que l’on veut récupérer (un Pokémon, une capacité, un type : feu, eau, plante…)

Et enfin, éventuellement, un filtre : l’identifiant précis du Pokémon, son nom…

Si j’indique /pokemon/pikachu/, l’API me renvoie un objet JSON concernant ce Pokémon. Si je termine ma requête sur /pokemon/ uniquement, alors j’aurais une liste des Pokémon.

Le Pokémon Pikachu
Pikachu est content d’avoir sa propre API REST

Ça ne vous rappelle rien ? C’est exactement le principe de WordPress avec les archives, et les single ! Du coup ça va être d’autant plus simple pour comprendre l’API REST intégrée avec WordPress.

Outils pour tester les API

Comme les API REST fonctionnent à base d’URL, vous l’aurez deviné, votre navigateur peut amplement suffire pour faire des tests (tant qu’aucune authentification n’est nécessaire).

Mais en ce qui concerne le résultat en JSON, le navigateur n’est pas très fort pour le mettre en forme de manière lisible. C’est pour cela qu’on va ajouter l’extension Chrome JSONView.

Mais pour aller encore plus loin, il existe un logiciel vraiment très sympa qui s’appelle Postman. Il permet de tester les requêtes API, et il est gratuit.

Il a une interface très complète qui conviendra autant aux débutants qu’aux utilisateurs plus chevronnés.

L'interface du logiciel Postman, pour gérer les API REST.
L’interface de Postman lors d’une requête

L’API Rest de WordPress

Bien, il ne reste plus qu’à transposer tout ça à WordPress, et à tester ! L’API REST est activée par défaut sur tous les sites, et n’expose bien sûr que les données publiques, en lecture.

Pour écrire des données, il faudrait un utilisateur authentifié. On verra ça justement dans le prochain cours. Pour l’instant, on va se contenter de lire des données publiques.

Attention

Ne désactivez pas l’API REST car elle est utilisée par l’éditeur de contenu (Gutenberg) et vous risqueriez de casser votre site !

Le saviez-vous ?

L’API REST a été intégrée dans le coeur de WordPress en 2015, et a été conçue (entre autres) par les développeurs de l’agence anglaise Human Made.

L’URL de base de l’API WordPress

Comme on l’a vu précédemment, une API répond sur une URL de base. Dans WordPress c’est /wp-json/.

Les URL par défaut pour l'API REST de WordPress
Tous les sites WordPress ont une API répondant sur cette URL

À la suite, on a l’identifiant de l’API, par défaut /wp/ pour WordPress. Mais d’autres extensions vont pouvoir venir ajouter leur propre API, et leurs propres routes. C’est le cas notamment de WooCommerce avec sa route /wc/.

Et enfin, on indique le numéro de version. WordPress en est à l’API version 2, et WooCommerce à la version 3.

Les points de terminaison

Pour obtenir ensuite des données, il va falloir ajouter à cette URL le nom de la ressource à récupérer.

Les points de terminaison de l'API REST de WordPress permettent d'accéder aux publications, utilisateurs...
Les terminaisons permettent d’accéder aux ressources

Pour les articles, ce sera /posts/, et pour les utilisateurs, ce sera /users/. On verra un peu après plus en détails les terminaisons qui s’offrent à nous.

Extensibilité de l’API

Vous l’aurez compris, si des extensions peuvent ajouter des routes (endpoint en anglais), et même leur propre API, alors vous aussi. Tout comme le CMS, son API est très flexible et vous permettra une grande liberté.

Étude de cas : l’API Rest WordPress chez WPChef

Justement, voici un exemple dans lequel l’API REST de WordPress m’a été grandement utile. Sur WPChef, nos stagiaires disposent d’un serveur d’exercice pour effectuer leurs devoirs.

Et dans l’objectif de les corriger, j’ai ouvert une route API sur chacun de leurs sites via l’installation d’un mu-plugin, ou Must Use Plugin. Cette terminaison me permet de récupérer diverses informations comme les extensions installées, la configuration du site, les utilisateurs…

Depuis notre interface, un bouton permet de lancer l’appel API, et une fois les données récupérées, elles sont analysées afin de définir si les critères ont été respectés.

Capture d'écran du système de correction assistée par API de WPChef
La correction assistée de WPChef

Tout cela a été rendu possible grâce à la présence d’une API REST sur tous les sites WordPress, et grâce à la possibilité de créer des routes sur mesure.

Et mine de rien, ce petit développement nous fait gagner aujourd’hui un nombre considérable d’heures.

Tester l’API REST de WordPress

Bon et bien j’imagine que vous avez hâte de tester l’API de votre site (ou de n’importe quel autre site WordPress) !

Lancer une requête en lecture

On va commencer par taper simplement l’URL de base, pour voir ce qu’il se passe.

Capture du résultat de la requête API, affiché dans le navigateur sous forme de JSON
Le JSON expose toutes les routes disponibles

Ce qui apparait à l’écran, c’est un sommaire qui va documenter toute l’API : les routes disponibles, les filtres…

Par définition, une API doit exposer sa structure et sa documentation, afin qu’un développeur ou même un programme, puisse comprendre son architecture et l’explorer.

On peut notamment voir qu’il existe une route /wp/v2/posts qui permet d’afficher tous les articles. On y apprend même qu’on va pouvoir ajouter des filtres, comme per_page, pour définir le nombre de résultats.

En fait, on a accès à presque tous les arguments disponibles dans la WP Query ! Mais on ne vas pas s’attarder là-dessus dans cette formation.

On apprend ensuite qu’il existe une autre route avec la même base : /wp/v2/posts/(?P<id>[\d]+). Il faut comprendre qu’on peut définir un identifiant, afin d’afficher un article en particulier. Alors essayons !

Les articles

En tapant /wp/v2/posts/ j’obtiens bien en effet la liste des articles :

La route affiche la liste des articles, sous forme d'un objet JSON
La liste des articles, au format JSON

Dans la liste, je vois que le second article possède l’identifiant 17418. Du coup si j’essaie cette fois /wp/v2/posts/17418, j’ai seulement cet article qui s’affiche !

Pour en revenir à la liste des articles, je vais maintenant essayer d’ajouter un filtre :

Plain Text

Dans le premier cas, je demande à récupérer 2 articles, à partir de la page 2, donc les articles en 3è et 4è position.

Dans le second cas, je filtre par catégorie, afin de n’afficher que les articles de la catégorie Tutoriels.

Il existe pleins d’autres filtres. Consultez la documentation pour en apprendre davantage.

Les pages et les Custom Post Types

De la même manière, vous pouvez listes les pages, ou une page, via cette fois la route /wp/v2/pages/.

Pour les Custom Post Types, il faudra explicitement les autoriser dans l’API lors de leur déclaration, et leur donner un nom de endpoint. Pour des recettes par exemple, on pourrait très bien définir /wp/v2/recipes/.

PHP
functions.php

Référez-vous au cours sur les types de publications personnalisées pour revoir comment créer un CPT dans votre thème.

Les utilisateurs

Il est possible de lister les auteurs du site via /wp-json/wp/v2/users.

Vous noterez que le mot de passe ou l’identifiant ne sont pas exposés publiquement, pour des raisons évidentes de sécurité !

Les clients WooCommerce sont également exclus de cette liste. Il existe justement une route privée dans Woo pour cela, en cas de besoin.

Bien sûr, il existe pleins d’autres routes encore, mais vous avez compris le principe. Pour en savoir plus sur les points de terminaison disponibles dans WordPress, consultez la documentation officielle :

Documentation API REST WordPress

Et en écriture ?

Pour écrire des données, c’est un peu plus compliqué, puisqu’il faut être authentifié. Eh bien oui, sinon n’importe qui pourrait saccager notre site ! Ce sera donc l’objet du prochain cours.


Il y aurait encore tellement de choses à dire sur les API REST, mais on va en rester là car vous avez déjà de bonnes bases. Si ce sujet vous intéresse et que vous voulez en savoir plus, je vous conseille le blog d’Octo qui possède pleins de ressources à ce sujet.

Dans le prochain cours, on va voir comment lire et écrire des données protégées dans WordPress via l’API, et comment s’authentifier (cours premium).

0

Questions, réponses et commentaires

Laisser un commentaire