Ce que vous devez savoir sur la nouvelle API WordPress REST

Publié: 2018-01-25

WordPress 4.4 a fait de l'API WordPress REST une partie du noyau.

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

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

Calypso – l'application de bureau de WordPress – en est un bel exemple. Calypso est construit à l'aide d'une seule application Javascript qui utilise l'API WordPress REST pour communiquer entre WordPress.com et le noyau.

Étant donné que l'API WordPress REST 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 cette présentation et ce didacticiel de l'API WordPress REST, je vais vous expliquer les bases de l'API WP REST et vous montrer comment vous pouvez l'utiliser pour créer un widget (plugin) qui affiche les derniers messages de Heroic Knowledge. Types de publication personnalisés de base.

Une introduction à l'API WordPress REST

Avant de voir comment utiliser l'API REST WordPress pour créer un widget (plugin), commençons par comprendre 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 devient possible via une API où le site Web extrait simplement les données de Twitter et les affiche.

Qu'en est-il du REPOS ?

REST est l'abréviation de REpresentational State Transfer .

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

Ainsi, lorsque nous parlons d'une API REST, nous entendons essentiellement une API qui utilise des méthodes HTML pour communiquer.

Et qu'en est-il du JSON ?

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

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

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 WordPress REST

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

Eh bien… l'API WordPress REST vous permet d'en faire plus avec WordPress.

Par example:

  1. Écrivez des applications dans n'importe quelle langue que vous connaissez et faites-la interagir avec un site WordPress (les 2 seules exigences étant que la langue de votre application doit utiliser des méthodes HTML et être capable d'interpréter JSON)
  2. Concevez des expériences d'administration et de contenu entièrement personnalisées
  3. Développer des applications à page unique sur WordPress

Et beaucoup plus.

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

Notre imagination est la seule limite à ce qui peut être fait avec l'API WordPress REST. En fin de compte, si vous voulez un moyen structuré, extensible et simple d'entrer et de sortir des données 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.

Voyons donc un tutoriel rapide sur la façon dont vous pouvez utiliser l'API REST de WordPress pour créer un widget (plugin) personnalisé.

Un tutoriel rapide sur la façon d'utiliser l'API WordPress REST

Si vous avez l'un de nos produits de base de connaissances, comme 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 didacticiel, mais n'oubliez pas que vous devrez adapter n'importe quel code à votre propre configuration.

Alors, prêt avec votre configuration locale ?

Super!

Maintenant, nous allons 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 WordPress REST pour communiquer avec ce deuxième site Web, et comme vous le savez maintenant, l'API WordPress REST consiste à faire en sorte que les conversations se produisent.

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

Et l'objectif final du tutoriel est de :

Sélectionnez les derniers articles de la base de connaissances publiés sur le site Web du centre d'aide et affichez-les 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 contenant tous les articles de la base de connaissances sera appelé le site Web " local " et le nouveau site Web sur lequel 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 didacticiel, nous aurions 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 WordPress REST) ​​à l'aide d'un widget (plugin) personnalisé.

Avec cela, nous sommes prêts à commencer :

Étape 1 : Commencez par copier le code passe-partout suivant dans un nouveau fichier .php et enregistrez-le dans le dossier plugins de votre site Web « externe ».

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

/**
* HeroThemes Example Widget
*/
class My_Widget extends WP_Widget { 

    //set up widget
    public function __construct() { 

        $widget_ops = array( 
                        'classname' => 'rest-api-test-widget',
                        'description' => 'This example provides a framework for how we will build our widget'
        );

        parent::__construct( 'my_widget', 'My Widget', $widget_ops );
    }


    /**
     * Outputs the content of the widget
     * @param array $args
     * @param array $instance
     */

    public function widget( $args, $instance ) {
        //outputs the content of the widget
        echo $args['before_widget'];

        if( !empty( $instance['title'] ) ) {
          echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'], $instance, $this->id_base ) . $args['after_title'];

        }

        // Main Widget Content Goes Here

        echo $args['after_widget'];
    }


    /**
     * Outputs the options form on admin
     * @param array $instance The widget options
     */

    public function form( $instance ) {
        //outputs the options form on admin
        $title = ( !empty( $instance['title'] ) ) ? $instance['title'] : ''; ?>

        <label for="<?php echo $this->get_field_name( 'title' ); ?>">Title: </label>

        <input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" 
        name="<?php echo $this->get_field_name( 'title' ); ?>" 
        type="text" value="<?php echo esc_attr( $title ); ?>" />
    
        <?php 
    } 

} 

 add_action( 'widgets_init', function(){ register_widget( 'My_Widget' ); } );

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 de fonctions du thème).

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

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

widget-admin

Étape 2 : Utilisez l'API WordPress REST 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 envoyé au 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 choses que nous devons savoir :

  • 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 (WP API 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 absolu de l'API devient :

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

(http://example.com est votre site Web "local")

Le parcours utilisé est :

 json/wp/v2/posts/

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

  • AVOIR
  • METTRE
  • EFFACER

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

Ainsi, votre première ligne de code interagissant avec l'API REST sera :

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

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

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

Tout ce que fait ce code est de vérifier quelle réponse est renvoyée. Si la réponse renvoie des messages, 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 JSON avec des données Post. Donc, tout ce que vous faites ici est de le décoder afin qu'il puisse être sorti.

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

Donc, à ce stade, vous avez réussi à communiquer avec votre site Web "local" à l'aide de l'API. Cette implémentation vous laisse une liste de publications à afficher.

L'étape suivante consiste à les afficher 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 terminé devrait ressembler à ceci : 

/**
* HeroThemes REST API Widget
*/
class REST_API_Widget extends WP_Widget { 

	//set up widget 
	public function __construct() { 
		$widget_ops = array( 	'classname' => 'rest-api-widget',
 								'description' => 'A REST API widget that pulls posts from a different website'
 		);
 		parent::__construct( 'rest_api_widget', 'REST API Widget', $widget_ops );
 	}

	/**
	* Outputs the content of the widget
	*
	* @param array $args
	* @param array $instance
	*/
	public function widget( $args, $instance ) {
		//change this url to the WP-API endpoint for your site!
		$response = wp_remote_get( 'https://example.com/wp-json/wp/v2/ht-kb/' );

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

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

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

		echo $args['before_widget'];
		if( !empty( $instance['title'] ) ) {
			echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'], $instance, $this->id_base ) . $args['after_title'];
		}
		
		//main widget content
		if( !empty( $posts ) ) {
		
			echo '<ul>';
			foreach( $posts as $post ) {
				echo '<li><a href="' . $post->link. '">' . $post->title->rendered . '</a></li>';
			}
			echo '</ul>';
			
		}

		echo $args['after_widget'];
	}

	/**
	* Outputs the options form on admin
	*
	* @param array $instance The widget options
	*/
	public function form( $instance ) {
		// outputs the options form on admin
		$title = ( !empty( $instance['title'] ) ) ? $instance['title'] : '';
		?>

		<label for="<?php echo $this->get_field_name( 'title' ); ?>">Title: </label>
		<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" 
		  name="<?php echo $this->get_field_name( 'title' ); ?>" 
		  type="text" value="<?php echo esc_attr( $title ); ?>" />
		
		<?php 
	} 

 } 

 add_action( 'widgets_init', function(){ register_widget( 'REST_API_Widget' ); } );

Une fois l'étape ci-dessus terminée, lorsque vous essayez maintenant de consulter votre site Web "externe", vous verrez une liste de vos messages du site Web "local" dans votre barre latérale.

widget

C'est super.

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

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

Utilisation de 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 au registre des arguments du type de publication pour le rendre accessible au public :


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

Mais comme dans notre cas, nous utilisons un plug-in pour alimenter le type de publication d'article de la base de connaissances, nous ne modifierons pas directement le fichier du plug-in 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 dans le thème enfant du site Web « local » :

La dernière version de KnowAll et Heroic Knowledge Base a déjà le support REST activé, cela peut être désactivé avec le filtre ht_kb_show_in_rest , mais vous pouvez modifier le code ci-dessous pour votre propre type de publication personnalisé. 
/**
* 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 WP REST.

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

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

Nous changeons essentiellement le /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 avez mis à jour votre widget et prévisualisé le site Web "externe", vous devriez maintenant voir les derniers articles de la base de connaissances.

widget-kb-contenu

Dernières pensées

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 pouvez modifier le plugin que nous venons de créer pour créer un champ de recherche qui utilise l'API WP REST pour rechercher les articles de la base de connaissances et renvoyer les résultats dans le widget.

Ou, vous pouvez 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 ! Obtenez simplement les bases et vous serez prêt.

Lectures complémentaires

Il y a beaucoup de contenu obsolète autour de l'API WordPress REST, alors assurez-vous de lire les mises à jour. J'ai lié à des ressources utiles tout au long de l'article, mais j'en énumère également quelques-unes ici.

Alors lisez-les et découvrez les différentes façons créatives d'utiliser l'API REST.

  • Manuel de l'API REST
  • FAQ sur l'API REST
  • API WP REST : est-ce là que nous allons ?

Si vous avez des questions sur la mise en œuvre de l'API WordPress REST, déposez-les dans les commentaires ci-dessous !