API REST WordPress : Tout ce que vous devez savoir

WordPress 4.4 a intégré l'API REST de WordPress au cœur du système.

Dans cet article, j'expliquerai pourquoi ce développement est énorme pour WordPress (et pour les auteurs de thèmes et de plugins en général) et je vous montrerai comment l'utiliser pour simplifier le processus de communication entre WordPress et d'autres applications.

L'API REST de WordPress permet également aux sites Web WordPress de se débarrasser de l'interface d'administration par défaut de WordPress pour offrir une expérience d'administration ou de contenu entièrement personnalisée en utilisant une pile technologique diversifiée.

Calypso – l'application de bureau de WordPress – en est un bel exemple. Calypso est construit à l'aide d'une application Javascript unique qui utilise l'API REST de WordPress pour communiquer entre WordPress.com et le cœur du système.

Étant donné que l'API REST de WordPress fait désormais partie intégrante du cœur de WordPress, il est important que les développeurs comprennent bien son fonctionnement et les nouvelles possibilités qu'elle ouvre pour interagir avec WordPress.

Et donc, dans cet aperçu et tutoriel sur l'API REST de WordPress, je vous présenterai les bases de l'API REST de WP ainsi que la manière dont vous pouvez l'utiliser pour créer un widget (de plugin) qui affiche les derniers articles des types d'articles personnalisés de la base de connaissances Heroic.

Un guide d'introduction à l'API REST de WordPress

Avant de voir comment utiliser l'API REST de WordPress pour créer un widget (de plugin), comprenons d'abord un peu mieux le terme.

Alors, que signifie API ?

API signifie *Application Program Interface*.

En termes simples, c'est un moyen de communication entre deux applications différentes.

Un exemple courant d'API en action est le Tweet Deck que de nombreux sites Web affichent. L'affichage de ce Tweet Deck est possible via une API où le site Web récupère simplement des données de Twitter et les affiche.

Qu'en est-il de REST ?

REST est l'acronyme de REpresentational State Transfer.

REST est un style architectural basé sur HTML pour la création d'API. Une architecture RESTful utilise les requêtes HTTP pour publier, lire, mettre à jour et supprimer des données entre deux sources.

Donc, quand nous parlons d'une API REST, nous entendons essentiellement une API qui utilise les méthodes HTML pour communiquer.

Et qu'en est-il de JSON ?

L'API REST de WordPress est au même format que l'API REST JSON de WordPress.

JSON (ou Javascript Object Notation) est un format d'échange de données minimaliste, basé sur du texte, qui est utilisé pour échanger des données de manière transparente entre différentes plateformes (même si les plateformes utilisent des langages différents).

JSON est une alternative légère aux solutions basées sur XML, ce qui le rend parfait pour les applications mobiles avec des limitations de bande passante.

Pourquoi utiliser l'API REST de WordPress

Vous vous demandez peut-être ce qui est si exceptionnel dans l'API REST de WordPress et pourquoi vous devriez vous en soucier.

Eh bien... l'API REST de WordPress vous permet de faire plus avec WordPress.

Par exemple :

1. Écrivez des applications dans n'importe quel langage que vous connaissez et faites-les interagir avec un site WordPress (les seules 2 exigences étant que le langage de votre application utilise des méthodes HTML et soit capable d'interpréter JSON).
2. Concevez des expériences d'administration et de contenu entièrement personnalisées
3. Développez des applications monopages (Single Page Applications) sur WordPress

Et bien plus encore.

Il est presque impossible de répertorier toutes les applications/interfaces/expériences potentielles qui peuvent être créées avec l'API REST. Le manuel de l'API REST de WordPress indique à juste titre :

Notre imagination est la seule limite à ce qui peut être fait avec l'API REST de WordPress. L'essentiel est que, si vous souhaitez un moyen structuré, extensible et simple d'obtenir des données dans et hors de WordPress via HTTP, vous voudrez probablement utiliser l'API REST.

Mais je sais que la mise en œuvre est toujours beaucoup plus difficile que la compréhension de la théorie.

Alors, voyons un bref tutoriel sur la façon dont vous pouvez utiliser l'API REST de WordPress pour créer un widget personnalisé (plugin).

Un bref tutoriel sur l'utilisation de l'API REST de WordPress

Si vous possédez l'un de nos produits de base de connaissances, tels que notre thème de centre d'aide KnowAll ou votre propre thème avec le plugin Heroic Knowledge Base, vous aurez un site avec une base de connaissances d'articles de support. L'utilisation de ces produits n'est pas nécessaire pour suivre les principes de ce tutoriel, cependant, gardez à l'esprit que vous devrez adapter tout code à votre propre configuration.

Alors, prêt avec votre configuration locale ?

Super !

Maintenant, ce que nous allons faire, c'est créer un autre site Web sur un serveur différent.

Alors pourquoi créons-nous ce deuxième site Web ?

Nous le faisons parce que nous voulons implémenter l'API REST de WordPress pour communiquer avec ce deuxième site Web, et comme vous le savez maintenant, l'API REST de WordPress vise à établir des conversations.

Nous allons donc utiliser l'API REST de WordPress pour que les deux sites Web se parlent et échangent des données.

Et le but final du tutoriel est de :

Sélectionner les derniers articles publiés de la base de connaissances du site Web du centre d'aide et les afficher dans un widget dans la barre latérale du nouveau site Web.

Pour les besoins de cet article, le site Web du centre d'aide qui contient tous les articles de la base de connaissances sera appelé le site Web « local » et le nouveau site Web où vous afficherez le widget sera le site Web « externe ».

À ce stade, je suppose que vous avez 1) votre site Web de centre d'aide « local », et 2) un nouveau site Web « externe » configuré sur un serveur différent.

Et à la fin du tutoriel, nous aurons réussi à afficher une liste d'articles de la base de connaissances du site Web « local » sur le nouveau site Web « externe » (via l'API REST de WordPress) en utilisant un widget personnalisé (plugin).

Sur ce, nous sommes prêts à commencer :

Étape n°1 : Commencez par copier le code boilerplate suivant dans un nouveau fichier .php et enregistrez-le dans le dossier des plugins de votre site web « externe ».

Voir le code complet de ce tutoriel sur l'API REST de WordPress ici.

Ce code crée un widget très simple qui affichera un titre de votre choix.

En ajoutant le code en haut du modèle et en l'enregistrant dans le répertoire des plugins, nous l'avons créé en tant que plugin (plutôt que d'ajouter le code au fichier functions du thème).

C'est une petite chose, mais créer un widget en tant que plugin de ce style vous permet de l'activer et de le désactiver, et aussi de le réutiliser dans d'autres thèmes plus tard si vous le souhaitez, sans avoir à copier-coller.

Une fois installé et activé, vous aurez un nouveau widget dans la zone Widgets du tableau de bord :

Étape n°2 : Utiliser l'API REST de WordPress pour récupérer les articles récents de la base de connaissances

Parce que vous ne voulez rien modifier ou supprimer dans ce développement, nous allons nous concentrer uniquement sur la fonction widget(). C'est là que le contenu du widget est affiché sur le site web « externe ».

Afin d'« obtenir » la liste des articles récents de la base de connaissances du site web « local », il y a quelques éléments que nous devons connaître :

• Le chemin de base de l'API (quelle API utiliser sur votre site, dans notre cas la dernière API WP)
• La route utilisée (l'API WP a plusieurs routes pour les différents ensembles de données et opérations disponibles)
• Le point de terminaison utilisé (Quelle action doit être effectuée)
• Paramètres (Les données associées à la requête)

Le chemin de base de l'API est toujours :

json/wp/v2/

Et donc le chemin API absolu devient :

http://example.com/json/wp/v2/

(http://example.com est votre site web ‘local’)

La route utilisée est :

json/wp/v2/posts/

À propos des points de terminaison : cette route a en fait trois points de terminaison qui sont différenciés par les méthodes HTTP. Ces points de terminaison sont :

• OBTENIR
• METTRE
• SUPPRIMER

Dans cet exemple, vous choisirez le point de terminaison GET afin de pouvoir récupérer (ou ‘obtenir’) une liste des derniers articles du site web ‘local’.

Votre première ligne de code interagissant avec l'API REST sera donc :

$response = wp_remote_get( 'http://products-website.com/wp-json/wp/v2/posts/' );

Ensuite, vous devez vérifier si des erreurs sont retournées :

if( is_wp_error( $response ) ) {
    return;
}

Tout ce code fait est de vérifier quelle réponse est retournée. Si la réponse retourne des articles, alors il n'y a pas d'erreur.

La dernière partie de cette section est :

$posts = json_decode( wp_remote_retrieve_body( $response ) );

if( empty( $posts ) ) {
   return;
}

$response est une chaîne encodée en JSON avec les données des articles. Donc, tout ce que vous faites ici, c'est de la décoder afin qu'elle puisse être affichée.

Encore une fois, ajoutez une vérification supplémentaire pour vous assurer que $posts n'est pas vide. Si c'est le cas, rien n'est retourné.

Ainsi, à ce stade, vous avez communiqué avec succès avec votre site web ‘local’ en utilisant l'API. Cette implémentation vous laisse avec une liste d'articles à afficher.

La prochaine étape consiste à les afficher réellement dans votre widget sur le site web ‘externe’.

Étape #3 : Affichez les derniers articles sur le site web ‘externe’ en ajoutant le code suivant :

if( !empty( $posts ) ) {
 
    echo '<ul>';
    foreach( $posts as $post ) {
        echo '<li><a href="' . $post->link. '">' . $post->title->rendered . '</a></li>';
    }
    echo '</ul>';
     
}

Le code de votre widget complet devrait ressembler à ceci :

Une fois l'étape ci-dessus terminée, lorsque vous essaierez de visualiser votre site web ‘externe’, vous verrez une liste de vos articles du site web ‘local’ dans votre barre latérale.

Tout cela est très bien.

Cependant, si vous vous souvenez, ce ne sont pas les bons articles car nous voulons seulement afficher les derniers articles de la base de connaissances.

Notre implémentation actuelle ne le fait pas car le plugin Knowledge Base utilise son propre type de publication personnalisé. Et comme les types de publication personnalisés ne sont pas disponibles publiquement pour les API par défaut, cela pose un problème. (Remarque : la dernière version de la base de connaissances est publiquement disponible pour l'API REST et la section suivante peut être ignorée)

Utiliser l'API REST avec des types de publication personnalisés

Pour rendre les types de publication personnalisés disponibles pour l'API REST, vous avez besoin d'une petite solution de contournement.

Ainsi, lors de la création d'un type de publication personnalisé, vous devez ajouter un nouveau paramètre aux arguments d'enregistrement du type de publication pour le rendre publiquement disponible :

'show_in_rest' = true,
'rest_base' = 'ht_kb',
'rest_controller_class' = 'WP_REST_Posts_Controller',

Mais comme dans notre cas, nous utilisons un plugin pour alimenter le type de publication d'article de la base de connaissances, nous n'allons pas modifier directement le fichier du plugin pour rendre les types de publication personnalisés disponibles pour l'API REST. (Modifier directement un fichier de plugin n'est jamais une bonne idée !)

Ce que nous allons faire à la place, c'est ajouter le code suivant au fichier functions.php du thème enfant pour le site web 'local' :

<?php

if ( ! defined( 'ABSPATH' ) ) exit;

/**
* Add rest support to an existing post type
*/
add_action( 'init', 'my_custom_post_type_rest_support', 25 );

function my_custom_post_type_rest_support() {
    global $wp_post_types;

    //set this to the name of your post type!
    $post_type_name = 'ht_kb';
    if( isset( $wp_post_types[ $post_type_name ] ) ) {
        $wp_post_types[$post_type_name]->show_in_rest = true;
        $wp_post_types[$post_type_name]->rest_base = $post_type_name;
        $wp_post_types[$post_type_name]->rest_controller_class = 'WP_REST_Posts_Controller';
    }
}

Désormais, le type de publication personnalisé 'ht_kb' est publiquement disponible pour l'API REST de WP.

Après avoir rendu le type de publication personnalisé disponible pour l'API REST de WordPress, nous devons maintenant corriger notre widget pour afficher les publications de ce type. Pour cela, nous reviendrons au code $response de l'étape n°2 et le mettrons à jour comme suit :

$response = wp_remote_get( 'http://example.com/wp-json/wp/v2/ht_kb/' );

Nous changeons essentiellement /posts/ en /ht_kb/ dans la route de l'API car 'ht_kb' est le nom du type de publication personnalisé du plugin.

Une fois que vous aurez mis à jour votre widget et prévisualisé le site web 'externe', vous devriez maintenant voir les derniers articles de la base de connaissances.

Dernières réflexions

Eh bien, comme nous l'avons vu, en utilisant quelques extraits simples de PHP et HTML, vous pouvez créer de nouvelles fonctions, widgets et plugins.

Vous pourriez modifier le plugin que nous venons de créer pour faire une boîte de recherche qui utilise l'API REST de WP pour rechercher les articles de la base de connaissances et renvoyer les résultats dans le widget.

Ou, vous pourriez utiliser l'authentification pour contrôler qui voit les résultats (utile si vous avez créé du contenu restreint).

Il y a tellement de choses que vous pouvez essayer ! Assurez-vous juste d'avoir les bases, et vous serez prêt.

Lecture complémentaire

Il y a beaucoup de contenu obsolète concernant l'API REST de WordPress, alors assurez-vous de ne lire que les informations mises à jour. J'ai lié à quelques ressources utiles tout au long de l'article, mais j'en liste quelques-unes ici aussi.

Alors lisez-les et découvrez les différentes manières créatives dont vous pouvez utiliser l'API REST.

• Manuel de l'API REST
• FAQ sur l'API REST

Si vous avez des questions sur l'implémentation de l'API REST de WordPress, posez-les dans les commentaires ci-dessous !