Dans la partie 1 de ce guide, j’ai jeté un coup d’œil à l’API HTTP en général. Nous avons appris ce qu’est HTTP, nous avons parlé de la structure des requêtes et des réponses HTTP et de la façon dont les types d’action et les URL s’associent pour déterminer ce que vous recevez en échange de votre requête. Dans cet article, nous allons examiner l’API HTTP de WordPress.

L’API HTTP de WordPress

Depuis la version 2.7 environ, WordPress dispose d’une API pour gérer HTTP. Elle se compose de 9 fonctions, dont vous n’en utiliserez probablement que quelques-unes. Les fonctions peuvent être classées en deux groupes distincts : l’un pour faire des requêtes, l’autre pour lire les résultats.

wp_remote_get(), wp_remote_post(), wp_remote_head() utilisent respectivement les méthodes GET, POST et HEAD pour demander des données à une URL donnée. La fonction wp_remote_request() est une fonction générale qui vous permet de spécifier une URL et une méthode pour l’accompagner.

Les fonctions utilisées pour lire les réponses sont également auto-décrites. wp_remote_retrieve_body() récupère le corps de la réponse, la fonction wp_remote_retrieve_header() récupère un en-tête nommé. La fonction wp_remote_retrieve_headers() renvoie tous les en-têtes sous forme de tableau, wp_remote_retrieve_response_code() vous donne le code de la réponse et wp_remote_retrieve_response_message() renvoie le message de la réponse.

C’est à peu près tout ce qu’il y a à faire, tout ce que nous devons savoir, c’est comment spécifier les en-têtes pour faire des requêtes appropriées.

Faire des requêtes

Utilisons la fonction wp_remote_get() pour faire une requête. Nous utiliserons le premier paramètre pour définir l’URL et le second pour ajouter des arguments. Vous pouvez trouver l’ensemble des paramètres pris en charge dans le Codex, je me concentrerai ici sur les informations d’en-tête.

Pour obtenir le message d’état d’un utilisateur de Twitter, vous devrez utiliser le chemin statuses/user_timeline.json à côté de l’URL https://api.twitter.com/1.1 et passer un jeton de porteur pour l’authentification – que j’ai généré précédemment. Le jeton de porteur doit être ajouté en tant qu’en-tête d’autorisation sous la forme de Bearer [TOKEN].

$token = 'Sijbwrf82wdaBief'; 
$response = wp_remote_get('https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=kinsta', array(
    'headers' => array(
        'Authorization' => 'Bearer ' . $token
    ),
));

Cette requête renvoie une multitude d’informations que vous pouvez obtenir avec la variable $response. Vous pouvez aussi utiliser les fonctions de type wp_remote_retrieve pour obtenir une partie de la réponse.

La plupart du temps, le corps contient les informations nécessaires, généralement au format JSON. En PHP, nous pouvons facilement convertir cela en tableau :

$data = json_decode( $response['body'], true )

Accéder à l’API Github

Construisons un exemple rapide qui répertorie nos derniers dépôts Github dans un widget WordPress. Tout d’abord, vous devez vous connecter à Github et aller dans votre profil, le modifier et aller dans « Jetons d’accès personnels » où vous pouvez générer un jeton.

Jetons d'accès Github
Jetons d’accès Github

Pour la prochaine étape, créons un modèle de widget vide. Ce widget aura deux options : un endroit où vous pourrez ajouter votre jeton d’API et un titre. Ce n’est pas la meilleure méthode car elle enregistre votre jeton dans la base de données, mais elle convient pour notre exemple.

class My_Github_Widget extends WP_Widget {

	public function __construct() {
		parent::__construct(
			'my_github_widget',
			'My Github Repos',
			array( 'description' => 'A widget that showcases your Github repos' )
		);
	}

	public function widget( $args, $instance ) {
		// Widget output
	}

	public function form( $instance ) {
		$token = ! empty( $instance['token'] ) ? $instance['token'] : '';
		$title = ! empty( $instance['title'] ) ? $instance['title'] : 'From Github';
		?>
<label for="get_field_id( 'title' ); ?>">Title <input class="widefat" id="get_field_id( 'title' ); ?>" name="get_field_name( 'title' ); ?>" type="text" value="">

<label for="get_field_id( 'token' ); ?>">Github API Token <input class="widefat" id="get_field_id( 'token' ); ?>" name="get_field_name( 'token' ); ?>" type="text" value="">

<?php } }

Je ne veux pas trop m’étendre sur la façon dont les widgets sont créés ici. Si vous voulez en savoir plus, jettez un coup d’œil au guide de l’API Widgets dans le Codex. L’important, c’est que le contenu de la méthode widget() produira le contenu de notre widget. À l’intérieur de cette fonction, nous nous connecterons à Github en utilisant une requête HTTP, puis nous formaterons et sortirons la réponse. Voici comment procéder – tout le code suivant va dans la méthode widget().

echo $args['before_widget']; 

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

$args = array( 
  'headers' => array( 
    'Accept' => 'application/vnd.github.v3+json', 
    'Authorization' => 'token 3f4f654ab31c2f15e839c74c952e5de2f562f1ee' 
  ) 
); 

$response = wp_remote_get( 'https://api.github.com/user/repos', $args ); 
$repos = json_decode( $response['body'], true ); 

if( !empty( $repos ) ) { 
  echo '<ul>'; 
  foreach( $repos as $repo ) { 
    echo '<li><a href="' . $repo['url'] . '" target="_blank">' . $repo['name'] . '</a></li>'; 
  } 
  echo '</ul>'; 
} 

echo $args['after_widget'];

Cela commence par le simple ajout de l’élément d’habillage et du titre du widget en haut et se termine par la fermeture de l’habillage du widget, la section principale du code se trouve entre les deux.

Tout d’abord, je configure mes en-têtes de requête HTTP. La première question peut être : comment savoir quels paramètres ajouter ? L’en-tête Authorization est le plus important, je l’ai lu dans la section Authentification de la documentation de l’API.

L’en-tête Accept n’est pas obligatoire, mais en haut de la même page des docs, le guide vous encourage à le fournir. J’utilise ensuite json_decode() sur le corps de la réponse et je parcours simplement le tableau résultant, créant ainsi une liste de liens.

Étapes suivantes

Si vous pensez que c’était facile, vous avez tout à fait raison, ça l’est ! La partie difficile est de s’assurer que vous avez couvert tous les angles sans gaspiller de ressources. Il y a deux problèmes avec le code qui nécessiteraient notre attention immédiate.

S’il y a un problème avec l’API – ce qui peut inclure des erreurs inconnues, des comptes à taux limité, etc. Nous vérifions simplement si le corps est vide ou non avant d’afficher la liste.

Si nous avons une erreur, le corps contiendra probablement des informations sur l’erreur, il ne sera donc pas vide dans ce cas non plus. Il est probable que nous listerions les éléments de la réponse d’erreur, mais comme ceux-ci n’auraient pas les propriétés url et name, nous nous retrouverions avec des éléments de liste vides et des avertissements PHP.

Le deuxième problème est que c’est tout simplement du gaspillage. Nous nous connectons à un service externe à chaque chargement de page, ce qui risque de peser sur nos serveurs et d’entraîner une limitation du compte sur Github. Même si ce n’est pas le cas, quelle est la probabilité que ta liste de repo Github change entre deux affichages de page, et quelle est l’importance d’avoir des informations à jour ici ?

Je recommanderais personnellement d’utiliser des transients dans un cas comme celui-ci. Un transient vous permet de stocker la réponse de la requête avec un délai d’expiration. Si vous définissez l’expiration sur un jour, les données seront récupérées une fois sur Github, puis directement dans votre base de données pendant les 24 heures suivantes. Après l’expiration, elles sont à nouveau récupérées sur Github et enregistrées dans la base de données.

Cela réduit vos appels d’API d’un par chargement de page à un par jour, ce qui est une énorme amélioration et pas trop de compromis non plus.

Résumé

WordPress permet d’interagir facilement avec les API du web. L’utilisation de quelques fonctions intégrées vous permettra d’extraire des données plus riches et plus pertinentes pour vos utilisateurs.

Associé à la sanitisation, à la vérification des erreurs et à un mécanisme de mise en cache, vous pouvezcréer une application efficace qui est non seulement plus utile, mais aussi moins gourmande en ressources que vous ne l’imaginez.

Si vous avez utilisé l’API HTTP de WordPress pour connecter WordPress à une API tierce, faîtes-le nous savoir, ce serait génial d’entendre parler de votre travail !

Daniel Pataki

Bonjour, je m'appelle Daniel et je suis directeur technique ici chez Kinsta. Vous me connaissez peut-être depuis Smashing Magazine, WPMU Dev, Tuts+ et d'autres magazines WordPress/Développement. Depuis WordPress et PHP, je passe la plupart de mon temps autour de Node, React, GraphQL et d'autres technologies dans l'espace Javascript. Quand je ne travaille pas à faire la meilleure solution d'hébergement de l'Univers, je collectionne les jeux de société, je joue au baby-foot au bureau, je voyage ou je joue de la guitare et chante dans un groupe assez mauvais.