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

L’API REST de WordPress

Lecture : 8 minutes • 17

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 :

Plain Text

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.

À éviter

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 é é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 de l’API Rest

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.

Et comme mon cours n’est pas encore disponible, je vous propose pour le moment l’excellent tutoriel de Pierre Saïkali : Créer des routes API sur WordPress.


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).

17

Questions, réponses et commentaires

  1. Nicolaide

    Le 28 novembre 2020

    bonjour , Merci pour ces explications, quand le prochaine cours sera t’il disponible “Lire et écrire des données via l’API Rest de WordPress authentification

    1. Maxime BJ

      Le 8 décembre 2020

      Je ne sais pas encore hélas. Mais pas avant un petit moment !

  2. MBAYA Serges

    Le 24 février 2021

    Merci pour ces explications. Bonne continuation oooh

  3. Enirevescode

    Le 11 juillet 2022

    Bonjour à toute l’équipe ! Je cherche le code pour intégrer une api externe dans mon site WP sans passer par 1 plugin. Le faire comme une grande ! Je cherche depuis quelques jours et je ne trouve que comment développer 1 api ou utiliser 11 plugin wp. Pour info j’ai fais un site et je souhaite avoir 1 encart avec la météo. Merci pour votre aide !

    1. Maxime BJ

      Le 11 juillet 2022

      Alors la première étape va être de créer ton propre plugin, pour mettre le code dedans. Je n’ai hélas pas pu écrire la formation à ce sujet pour le moment.
      Une fois que tu as la base de ton plugin, active-le et tu vas pouvoir écrire le code que tu veux dedans. Là, il faudra lire la documentation de l’API météo, il y aura peut-être un SDK, un kit de développement à intégrer pour te fournir des fonctions pour lire plus simplement l’API. Si ce n’est pas le cas, tu vas probablement pouvoir utiliser cURL pour récupérer les informations à distance. Et avec WordPress on fait du cURL via la fonction wp_remote_get();
      Dans tous les cas, c’est la documentation de l’API qui devrait t’aider !

      1. Enirevescode

        Le 11 juillet 2022

        Merci Maxime ! Le token devra etre mis dans le SDK ou dans le plugin ? En tout cas encore merci car cela dessine + clairement le chemin de l’intégration d’une API. Est ce décrit dans les cours premium ? Cdt

        1. Maxime BJ

          Le 11 juillet 2022

          le SDK est importé comme une dépendance externe, il ne faut donc pas la modifier. Tu vas du coup avoir une fonction pour appeler et initialiser le SDK, et souvent c’est à ce moment que tu passes ta clé API. Pour aller plus loin, tu peu en PHP utiliser des variables d’environnement :un fichier .env contient toutes les clés API et mots de passe sensible, et ce fichier n’est pas versionné pour éviter que ta clé finisse sur Github. Bon là c’est déjà plus avancé et tu n’as absolument pas besoin de tout ça dans un premier temps.

  4. Rapp

    Le 11 août 2022

    Bonjour,

    Merci pour toutes ces explications. C’est un peu compliqué pour moi.

    j’ai une question, j’ai la connexion avec mon fournisseur par le biais de la clé API Rest qui se trouve dans les réglages WooCommerce. Mais je cherche le moyen de l’intégrer pour mes produits

    Je vous remercie

    1. Maxime BJ

      Le 11 août 2022

      Je ne suis pas sûr d’avoir compris ton besoin. La formation actuelle ne traite pas de WooCommerce, il faudra attendre la formation Woo pour cela.

      1. Rapp

        Le 12 août 2022

        Merci Maxime

  5. Marie

    Le 29 juin 2023

    Bonjour Maxime,

    Je n’arrive pas à enregistrer mes modifications de publications/articles… J’ai toujours ce message d’erreur : ” La mise à jour a échoué. La réponse n’est pas une réponse JSON valide.”

    J’ai remarqué un message d’amélioration dans la santé de mon site :
    “L’API REST est l’une des façon pour WordPress ou d’autres applications de communiquer avec le serveur. Par exemple, l’écran de l’éditeur s’appuie sur celui-ci pour afficher et enregistrer vos publications.

    L’API REST n’a pas traité correctement le paramètre de la requête context.”

    Je pense que le problème vient d’ici. Savez vous comment résoudre ce problème ?

    Merci beaucoup
    Marie

    1. Maxime BJ

      Le 29 juin 2023

      Il va falloir que tu actives le log d’erreur de ton site. C’est dû à une erreur PHP qui est causée lors de l’exécution de WordPress. Pour cela, ajoute define( ‘WP_DEBUG’, true ); et define( ‘WP_DEBUG_LOG’, true ); dans le wp-config.php de ton site. Voici la documentation à ce sujet : https://fr.wordpress.org/support/article/debugging-in-wordpress/.
      Ensuite, regarde le fichier wp-content/debug.log pour connaitre la cause du problème.

      1. marie

        Le 29 juin 2023

        Merci de ta réponse.
        J’ai fait comme tu as dit, mais je ne trouve pas mon fichier debug.log dans wp-content.
        J’ai essayé de le trouver via des forums et fait d’autres manips mais introuvable.
        Je vais télécharger Query Monitor pour tester.

        Merci de ton aide

        1. Maxime BJ

          Le 29 juin 2023

          Tu peux sinon voir l’erreur dans la console du navigateur. Onglet réseau (network) et en cliquant sur la requête Ajax dans la liste (tu peux filtrer par fetch/XHR). Dans le sous onglet Preview tu devrais voir l’erreur avant le json.

          1. Marie

            Le 29 juin 2023

            Cool,merci !
            Effectivement je vois des erreurs, je vais creuser dessus 😉

  6. A. Sfar - Clever

    Le 8 février 2024

    Magnifique poste qui reste très à jour et utile. Nous utilisons en effet l’API pour intégrer le contenu WP dans les applications mobiles de nos clients, et c’est super pratique.

    Merci beaucoup,

    1. Maxime BJ

      Le 8 février 2024

      Effectivement, et Gutenberg utilise aussi l’API rest pour récupérer et enregistrer les informations de l’éditeur en direct et sans rechargement de page. l’arrivée de l’API avait propulsé WP dans le futur.

Laisser un commentaire