Le guide complet des bases de l’API REST WordPress

L’API REST de WordPress est en train de changer WordPress. Vous ne l’avez peut-être pas remarqué, comme c’est souvent le cas sous le capot, mais les implications de l’API REST font une énorme différence pour l’avenir de WordPress, tant au niveau de son code de base que de ses utilisations.

Si vous n’avez pas travaillé avec l’API REST  de WordPress, vous vous demandez peut-être de quoi il s’agit. Commençons donc par regarder ce qu’est l’API REST.

Qu’est-ce que l’API REST de WordPress ?

L’API REST de WordPress est une interface que les développeurs peuvent utiliser pour accéder à WordPress depuis l’extérieur de l’installation WordPress elle-même. Vous y accédez à l’aide de JavaScript, ce qui signifie que cela peut être utilisé pour créer des sites Web interactifs et des applications.

REST signifie Representational State Transfer et API signifie Application Programming Interface. Voyons ce que chacun de ces termes signifie.

Qu’est-ce que l’Application Programming Interface (API) ?

Une interface de programmation d’application, ou API, est définie comme :

« Une interface ou un protocole de communication entre un client et un serveur destinée à simplifier la construction d’un logiciel côté client. »

Si vous n’êtes pas familier avec les API, cela n’aidera peut-être pas beaucoup. En termes plus simples, une API est un ensemble de code qui permet à un système d’interagir (ou « interface ») avec un autre. Si vous avez déjà eu l’occasion d’ajouter une carte Google à votre site WordPress, vous avez utilisé l’API Google Maps, qui permet à votre site WordPress de s’interfacer avec Google Maps.

Ces systèmes n’ont pas besoin d’être complètement séparés. WordPress a déjà de multiples APIs, pour des choses comme les extensions, les réglages et les codes courts. Celles-ci peuvent être utilisées par les développeurs d’extensions et de thèmes pour interagir avec le noyau WordPress et faire bouger les choses (comme créer des codes courts et ajouter des écrans de réglages dans l’administration de WordPress).

La différence avec la REST API est qu’elle permet aux systèmes extérieurs à votre installation WordPress d’interagir avec WordPress, et c’est là que la partie REST intervient.

Qu’est-ce que la Representational State Transfer (REST) ?

La Representational State Transfer, ou REST, fournit des normes que les systèmes Web peuvent utiliser pour s’interfacer entre eux. Sans le REST, deux systèmes ne pourraient pas se comprendre et donc s’envoyer des données dans les deux sens.

Pour qu’une application soit RESTful, elle doit se conformer à cinq principes :

1. Interface uniforme. Les URL utilisées pour accéder aux ressources du système doivent être uniformes, cohérentes et accessibles par le biais d’une approche commune telle que GET (d’autres bientôt).
2. Client-serveur. Les applications client et les applications serveur doivent être séparées, de sorte qu’elles puissent être développées indépendamment les unes des autres. Si la technologie côté serveur (ex : WordPress) change, l’application côté serveur (une application, par exemple) doit toujours pouvoir y accéder par la même méthode simple.
3. Sans état. Le serveur ne change pas d’état lorsqu’une nouvelle requête est faite en utilisant l’API. Il ne stocke pas les requêtes qui ont été faites.
4. Cachable. Toutes les ressources doivent pouvoir être mises en cache, afin d’améliorer la vitesse et la conformité aux standards du web. La mise en cache peut être implémentée sur le serveur ou côté client.
5. Système à couches. Un système RESTful vous permet d’utiliser plusieurs couches pour y accéder, en stockant les données dans des serveurs intermédiaires si besoin. Le serveur ne peut pas dire si le client final y est directement connecté.

Toutes ces contraintes concernent les pages Web et les applications et régissent la façon dont une application peut s’interfacer avec l’API.

Qu’est-ce que cela signifie pour WordPress ?

L’association de REST et API signifie que la REST API de WordPress est un ensemble de code conçu pour permettre à d’autres systèmes de s’interfacer avec WordPress et qu’il est construit de manière à ce que ces systèmes puissent se comprendre mutuellement.

Cela signifie qu’un site Web tiers ou une application mobile, par exemple, peut accéder à votre base de données WordPress, récupérer des données à partir de celle-ci, et y ajouter des données.

Il y a un certain nombre d’implications et d’utilisations pour cela, cependant.

Comprendre l’API REST de WordPress

La REST API de WordPress a été développée en réponse aux changements dans la façon dont les sites Web et les applications sont développés et à la nécessité d’ouvrir WordPress plus largement.

Contexte de l’API REST de WordPress

La REST API de WordPress a été réalisée en tant que partie intégrante du noyau dans la version 4.7 en décembre 2016, mais elle existait déjà sous la forme d’une extension avant cela.

Elle est conçue pour prendre en charge une gamme d’applications basées sur WordPress et pour transformer WordPress d’un système gestion de contenu à une plateforme d’application.

Elle est largement utilisée par WordPress.com, dont l’interface JavaScript utilise la REST API pour s’interfacer avec la base de données WordPress. Elle est également utilisée par l’interface d’édition de Gutenberg, qui est devenue une partie du noyau en 2019.

La REST API élargit la gamme des applications pour lesquelles WordPress peut être utilisé. Alors qu’un système de gestion de contenu excelle dans l’exploitation d’un site Web complexe, une plateforme d’application peut également être utilisée pour alimenter des applications Web d’une page ou des SPAs (si vous avez déjà utilisé des Google docs, vous en avez utilisé un).

Dans ces derniers, le contenu est rafraîchi lorsque l’utilisateur effectue des actions, au lieu de charger de nouvelles pages. Parce qu’il utilise JavaScript (un langage côté client) au lieu de PHP (un langage côté serveur), il peut faire bouger les choses dans le navigateur de l’utilisateur sans avoir à envoyer constamment des requêtes au serveur.

Implications pour les utilisateurs et les développeurs de WordPress

Si vous êtes un utilisateur et/ou un développeur travaillant avec WordPress, la REST API a un certain nombre d’implications.

Pour les utilisateurs, il s’agit notamment de :

• Modifications de l’interface, y compris l’éditeur Gutenberg.
• Modifications et améliorations apportées à l’application mobile WordPress.
• Les écrans d’administration WordPress hébergés par l’utilisateur ressemblent plus à WordPress.com au fil du temps.

Pour les développeurs, il y a des implications et des possibilités plus larges :

• La possibilité de créer des SPAs à l’aide de la REST API, en récupérant les données de WordPress mais avec un aspect très différent de WordPress.
• La capacité d’intégrer WordPress à d’autres technologies et systèmes d’interface publique.
• La possibilité de développer avec WordPress si vous êtes un développeur d’interface publique qui n’écrit pas en PHP.
• Pour les développeurs PHP, un besoin croissant d’étendre vos compétences pour inclure JavaScript.
• Des changements spécifiques tels que la nécessité de construire des blocs Gutenberg au lieu de méta-boîtes dans les écrans de modification de page et d’article.

Avec le temps, la REST API de WordPress signifiera qu’une plus grande partie du noyau WordPress sera écrite en JavaScript et non en PHP. Si vous êtes un développeur WordPress, cela signifie que vous devrez apprendre JavaScript.

Comment accéder à l’API REST de WordPress

Comment accéder à la REST API de WordPress ?

Pour accéder à la REST API de WordPress, vous devez accéder à votre site via la ligne de commande. Avec WordPress, cela s’appelle WP-CLI. Vous ne faites rien via vos écrans d’administration ou en accédant directement au code sur votre site.

Voyons comment vous pouvez commencer.

Accès à WP-REST via WP-CLI

WP-CLI est l’interface de ligne de commande WordPress. Elle vous permet d’accéder et de travailler avec WordPress via l’interface en ligne de commande (CLI) de votre ordinateur. WP-CLI est préinstallé avec tous les plans d’hébergement Kinsta.

Pour accéder à l’interface CLI, ouvrez le terminal sur un Mac ou sous Linux, ou l’invite de commandes sous Windows.

Pour accéder à un site distant, vous avec besoin de SSH sur votre serveur pour y accéder via WP-CLI (Vous ne pouvez pas vous connecter via SSH ? Apprenez comment réparer l’erreur « Connexion refusée » de SSH).

Pour accéder à un site local vous devez simplement utiliser la structure de répertoire correcte à partir de la ligne de commande. C’est une bonne idée d’expérimenter la REST API sur un site de test local avant de l’essayer sur un site en production.

Vous devrez accéder spécifiquement à la REST API de votre site, comme ceci :

http://yoursite.com/wp-json/wp/v2

Vous pouvez ensuite ajouter des éléments pour accéder à certains types de données, que nous examinerons plus en détail sous peu. Ces éléments s’appellent des points de terminaison (endpoints).

Authentification

Une fois que vous avez accédé à votre site, vous devrez peut-être passer par l’authentification. Certains points de terminaison sont publics et ne nécessitent pas d’authentification, alors que d’autres en ont besoin.

Ici, vous n’êtes pas connecté à l’administration de votre site : la REST API fait les choses un peu différemment.

Pour pouvoir authentifier votre site via WP-CLI, vous devrez installer une extension d’authentification. Pour les installations de développement, l’extension Basic Auth fait le travail et est simple à utiliser.

Cependant, pour les sites en production, vous devriez utiliser une forme d’authentification plus robuste telle que l’extension JWT Authentication, qui utilise JSON Web Token et est plus sécurisée.

Vous pouvez ensuite utiliser la ligne de commande pour accéder aux données et inclure l’authentification.

L’exemple ci-dessous utilise curl pour tester la connexion à WordPress. Il produira une liste de brouillon d’articles.

curl -X GET --user username:password -i http://yoursite.com/wp-json/wp/v2/posts?status=draft

Les brouillons d’articles ne sont pas des informations publiques, vous avez donc besoin d’une authentification pour y accéder. Mais si vous recherchez des données publiques, vous n’avez pas besoin d’authentification. Ainsi, pour récupérer une liste d’articles qui ont été publiés, vous pouvez utiliser :

curl -X GET http://yoursite.com/wp-json/wp/v2/posts

Cela permettrait de récupérer tous les articles publiés parce qu’ils sont publics.

Vue d’ensemble des commandes de l’API REST de WordPress

Une fois que vous avez accédé à votre site et que vous savez comment utiliser l’authentification (et même si vous en avez besoin), vous devrez utiliser l’une des nombreuses commandes pour interagir avec votre site.

Les commandes que vous devrez utiliser sont :

• GET récupère une ressource telle qu’un article ou d’autres données.
• POST ajoute une ressource au serveur, telle qu’un article, une pièce jointe ou une autre ressource.
• PUT peut être utilisée pour modifier ou mettre à jour une ressource qui se trouve déjà sur le serveur.
• DELETE supprime une ressource du serveur. Utilisez-la avec précaution !

Examinons chacun d’entre elles à tour de rôle.

GET

La commande GET est probablement la plus utilisée : elle récupère les données. L’exemple ci-dessous (que tu utilises une fois que tu as accédé à ton site avec succès) va chercher une liste de toutes les pages publiées sur votre site :

GET http://yoursite.com/wp-json/wp/v2/posts/?status=published

Notez que je n’ai pas inclus le chemin complet vers votre site dans la ligne ci-dessus car vous y avez déjà accédé en utilisant WP-CLI.

Après avoir récupéré ces données, vous pouvez les utiliser pour renseigner votre prochaine étape. Vous pouvez supprimer un de ces articles, le modifier ou le mettre à jour. Vous pourriez simplement publier des articles sur votre application web.

Supposons que vous vouliez aller chercher le dernier article. Vous utiliseriez ceci :

GET http://yoursite.com/wp-json/wp/v2/posts/?per_page=1

Il y a un certain nombre d’arguments que vous pouvez utiliser lorsque vous travaillez avec des articles. Voir le WordPress REST API Handbook pour en savoir plus.

POST

Utilisez POST pour ajouter de nouvelles données ou ressources à votre site.

Ainsi, par exemple, si vous vouliez créer un article, vous commenceriez par utiliser une commande POST :

POST http://yoursite.com/wp-json/wp/v2/posts/

Cela créerait un nouveau brouillon d’article.

Vous pouvez ensuite mettre à jour l’article en utilisant une commande PUT pour le modifier.

Avec une commande POST, vous pouvez également ajouter d’autres ressources que les articles, y compris les pièces jointes et autres types de publication.

Pour ajouter une page à votre site, vous pouvez utiliser quelque chose comme ceci :

POST http://yoursite.com/wp-json/wp/v2/posts/pages

Cela créerait une page vide de la même manière que vous créeriez un article vide.

PUT

La commande PUT vous permet de modifier une ressource existante, y compris les articles.

Supposons que vous ayez un certain nombre de brouillons d’articles sur votre site. Vous voulez les vérifier et en mettre à jour un pour la publier.

Vous pouvez commencer par chercher une liste de tous les brouillons d’articles :

POST http://yoursite.com/wp-json/wp/v2/posts/?status="draft"

Le système vous donnera une liste de tous les brouillons d’articles actuels. Vous pouvez modifier le statut de l’un d’entre eux à l’aide de son ID :

PUT http://yoursite.com/wp-json/wp/v2/posts/567

Le serveur retournera un statut 200 – OK vous indiquant que la requête PUT a bien modifié l’article.

{
"status" = "publish"
}

Ou vous pouvez ajouter du contenu à l’article et le publier :

{
"status" = "publish"
"content" = "content here"
}

Le serveur retournera un statut 200 - OK vous indiquant que la requête PUT a bien modifié l’article.

DELETE

La commande DELETE fait ce à quoi vous vous attendez : elle supprime une ressource. Par défaut, si vous l’utilisez pour supprimer un article, elle le mettra dans la corbeille au lieu de le supprimer définitivement.

Donc si vous vouliez déplacer dans la corbeille l’article que vous venez de créer, vous utiliseriez ceci :

DELETE http://yoursite.com/wp-json/wp/v2/posts/567

Cependant, si vous vouliez contourner la corbeille et le supprimer définitivement, vous utiliseriez l’argument force :

DELETE http://yoursite.com/wp-json/wp/v2/posts/567?force=true

Ceci supprime définitivement l’article sans possibilité d’annulation, elle doit donc être utilisée avec prudence.

Quand ne pas utiliser l’API REST de WordPress

La REST API de WordPress ne sera pas toujours la bonne approche pour développer un site Web ou une application. Voici quelques considérations dont vous devez tenir compte avant de l’utiliser pour le développement :

Compatibilité

Si votre application doit être utilisée sur des périphériques qui n’exécutent pas JavaScript ou par des utilisateurs qui risquent de le désactiver, elle ne fonctionnera pas si vous utilisez la REST API.

Un site WordPress codé en PHP produira du HTML donc il ne souffrira pas de ce problème. Les périphériques qui n’utilisent pas JavaScript sont de plus en plus rares, mais si vous développez spécifiquement pour eux, la REST API ne fonctionnera pas.

De même, si vos utilisateurs sont susceptibles de désactiver JavaScript, travailler avec la REST API posera problème. Certains utilisateurs désactivent JavaScript dans leur navigateur pour des raisons d’accessibilité ou de sécurité.

Accessibilité

Les sites ou applications développés en JavaScript ne sont pas toujours aussi accessibles que ceux développés en HTML.

Cela est dû en grande partie à la façon dont JavaScript est utilisé pour fournir un contenu dynamique qui peut ne pas fonctionner correctement avec les lecteurs d’écran et peut causer des problèmes aux personnes ayant une déficience visuelle ou une épilepsie photosensible.

L’utilisation de la REST API pour accéder à votre site WordPress et produire des données sous une forme conçue pour être accessible vous permet de surmonter ces problèmes, mais cela vaut la peine de vérifier l’accessibilité de votre site pendant son développement.

SEO

Les applications d’une seule page, qui se rafraîchissent fréquemment, peuvent parfois causer des problèmes de référencement. C’est parce que le contenu qui n’est pas livré lorsque la page est la première affichée peut ne pas être indexé par les moteurs de recherche.

Google et d’autres moteurs de recherche sont en train de rattraper le fait que de nombreux sites Web sont maintenant alimentés par des SPA et les indexent de manière appropriée. Mais cela vaut la peine de faire un audit SEO de tout site que vous développez en utilisant la REST API.

Comment désactiver l’API REST de WordPress

Si vous ne voulez pas que les applications puissent accéder aux données de votre site en utilisant l’a REST API, vous pouvez la désactiver. N’oubliez pas que les données publiques peuvent être accessibles à tout le monde, pas seulement à vous.

Pour ce faire, vous pouvez installer l’extension Disable WP REST API. Elle désactive la REST API pour quiconque n’est pas connecté à votre site.

Alternativement, vous pouvez ajouter du code au fichier de fonctions de votre thème ou écrire votre propre extension. Il est préférable d’écrire une extension car ce n’est pas une fonctionnalité spécifique au thème.

Dans votre extension, ajoutez seulement deux lignes :

add_filter( 'json_enabled', '__return_false' );
add_filter( 'json_jsonp_enabled', '__return_false' );

Ceci désactivera complètement la REST API de votre site. Cela peut avoir des effets d’entraînement pour vos écrans d’administration, alors assurez-vous que tout fonctionne bien une fois que vous l’avez ajouté.

Applications du monde réel utilisant l’API REST de WordPress

La REST API offre des possibilités passionnantes pour l’avenir de WordPress. Voici quelques exemples d’applications et de sites utilisant la REST API de WordPress pour créer des SPAs ou pour relier WordPress à d’autres sites et technologies.

WordPress.com

Les écrans d’administration de WordPress.com sont entièrement construits en utilisant la REST API pour fournir un SPA avec lequel les utilisateurs interagissent pour gérer leur site.

Cela permet une communication dynamique entre l’interface et le serveur et donne une interface conviviale que WordPress.org est susceptible d’imiter dans le temps.

L’éditeur de bloc (Gutenberg)

Également dans les écrans d’administration de WordPress, mais cette fois aussi dans WordPress, l’éditeur de blocs Gutenberg utilise la REST API pour communiquer avec votre base de données et créer des blocs.

Pour que les types de publications fonctionnent avec l’éditeur Gutenberg, ils doivent avoir la REST API activée. Ce qui veut dire que si vous enregistrez un type de publication personnalisé et que vous utilisez Gutenberg, vous devrez ajouter la ligne suivante pour activer l’éditeur de bloc pour ce type de publication :

"show_in_rest" = true;

Event Espresso

Event Espresso est une extension WordPress qui permet aux utilisateurs d’organiser et de publier des événements. Il utilise la REST API pour que les utilisateurs puissent accéder aux données depuis l’extérieur de WordPress. Cela signifie que vous pouvez créer des applications mobiles ou des SPA pour gérer vos événements.

UsTwo

UsTwo est une agence numérique dont le site a été construit en utilisant la REST API en tant qu’application à page unique. Ceci combine une interface publique construite avec React et une administration propulsée par WordPress (lecture suggérée : Votre guide pour démarrer et gérer une agence WordPress avec succès).

Le contenu de leur page unique est modulaire, avec une structure différente d’une page WordPress standard. Pour ce faire, ils utilisent une extension de création de page personnalisée qui permet à leur équipe d’ajouter du contenu modulaire au site.

USA Today

Le site Web d’USA Today a été reconstruit en utilisant l’intégration de la REST API de WordPress avec les systèmes et modules existants sur le site.

La REST API permettait de pousser le contenu du site vers d’autres endroits tels que Facebook Instant Articles et Apple News, en utilisant JSON. Ils ont également écrit un jeu social en ligne construit en JavaScript pour leur section sportive.

Résumé

L’API REST de WordPress présente des défis passionnants mais aussi des opportunités intéressantes pour les utilisateurs et les développeurs de WordPress. C’est le futur de WordPress et est susceptible de changer radicalement la façon dont nous développons avec WordPress et la façon dont nous l’utilisons.

Que pensez-vous de la REST API ? L’avez-vous utilisée pour certains de vos projets ? Dites-le nous dans la section des commentaires ci-dessous !