Les API de type REST sont de plus en plus prisées par les développeurs car elles sont un moyen de communication entre leurs applications et des services web tels que ceux de Twitter, MailChimp ou GitHub. L’arrivée de l’API REST de WordPress disponible via plugin (mais prévue dans le  noyau pour Décembre), propose une occasion idoine pour étudier l’API HTTP qui existe déjà dans WordPress. Dans ce tutoriel, je vous expliquerai ce qu’est l’API HTTP de WordPress et vous montrerai comment l’utiliser.

L’API HTTP

L’API HTTP de WordPress est un moyen de transmettre des messages à travers le protocole HTTP, d’une application d’un service web ou d’un autre site à WordPress et vice versa. Pour arriver sur cette page, votre navigateur à effectuer une requête HTTP vers les serveurs de BlogPasCher. Ces derniers ont répondu en renvoyant une réponse contenant ce que vous voyez en ce moment. L’API REST de WordPress lui permet désormais de participer à ce genre de système requête/réponse permettant ainsi un découplage entre l’interface graphique et le noyau de la plateforme. Mais pour profiter de cela, vous devez apprendre à utiliser l’API HTTP de WordPress qui propose un ensemble de méthodes et d’utilitaires pour envoyer des requêtes HTTP.

Les méthodes HTTP et les ressources

Le protocole HTTP est centré autour des méthodes et des ressources. Les ressources définissent ce sur quoi vous voulez produire action, et les méthodes le type d’action à produire. Plus pratiquement, les ressources sont des URLs vers des objets sur internet (par exemple cet article). Du côté des méthodes, il en existe un certain nombre dont les plus importantes sont :

GET : pour récupérer une ressource
POST : pour créer une ressource
PUT : pour modifier une ressource
DELETE : pour supprimer une ressource

Exemple de requête avec l’API HTTP

Pour se faire les doigts, voyons comment envoyer une requête simple avec l’API HTTP. Nous utiliserons la fonction wp_remote_get pour interroger le serveur de Google et en récupérer la page d’accueil. Cette fonction prend deux paramètres dont le premier est la ressource et le second une liste d’options pour spécifier des détails. Sans plus attendre passons à l’action.

$test = wp_remote_get( 'http://google.com' );
echo "<pre>"; 
var_dump($test); 
echo "</pre>";

Le retour de wp_remote_get est contenu dans la variable $test, et représente le contenu de la page d’accueil que Google à renvoyé suite à notre requête. La ligne var_dump($test); vous permet de voir les éléments renvoyés dans la réponse.

La section des headers contient des informations additionnelles sur les messages. Certaines API REST auront besoin que vous envoyiez des informations spécifiques dans les requêtes qui leurs sont adressées.

La section response contient le code de statut et la description de la réponse. Vous avez peut être déjà entendu parler d’erreur 404 pour les pages non trouvées, erreurs 501 de serveurs, ou de redirection 301 et 302. Ces nombres sont des codes d’erreurs. Le site W3.org possède une liste de toutes les codes d’erreurs HTTP et leur description.

La section body contient la réponse proprement dite, et est l’endroit où vous devrez regarder lorsque tout se passe bien. Dans cet exemple on reçoit de l’HTML, celui de la page d’accueil de Google. Il est très courant pour les API REST de renvoyer des réponses au format JSON. Certaines API, comme nous le verrons, vous exigeront d’inclure une chaîne de caractères dans la section body de votre requête.

La section cookies contiendra tous les cookies reçus avec le message.

Comme vous le constatez vous même, envoyer des requêtes à l’aide de l’API HTTP de WordPress n’est pas difficile. Par contre ce qui peu l’être avec les API REST c’est qu’elles sont pointilleuses sur les détails des informations envoyées, ce qui est une bonne chose pour la cohérence. Donc faites attention en lisant la documentation des APis que vous utilisez.

Interroger des APIs

Il est clair que la majeure partie d’entre vous va utiliser l’API HTTP pour interagir avec des API REST. Vous devrez donc employer le second paramètre de la fonction wp_remote_get afin de préciser un certain nombre de choses, vous authentifier, affiner vos résultats etc… Commençons avec un exemple simple, comme récupérer les pins d’un mur Pinterest. Toute API qui se respecte exige une authentification, mais on va la contourner ici en générant un access token (jeton d’accès). Le code !

$request = wp_remote_get( 'https://api.pinterest.com/v1/boards/<identifiant-board>/home-office/pins/?access_token=<votre-access-token>' );
$pins = json_decode( $request['body'], true );
if( !empty( $pins['data'] ) ) {
    echo '<ul>';
    foreach( $pins['data'] as $pin ) {
        echo '<li><a href="' . $pin['url'] . '">' . $pin['note']. '</a></li>';
    }
    echo '</ul>';
}

Assurez vous bien de remplacer sur la première ligne <identifiant-board> par l’identifiant du mur Pinterest et <votre-access-token> par le jeton d’accès que vous avez générer vous même. La réponse est en JSON, donc la seconde ligne la décode. Les pins sont contenus dans $pins[‘data’], donc on le parcours et on affiche les pins dans une liste. Vous pouvez coller ce code dans un fichier template de votre thème et en voir le résultat.

L’authentification

Pour cette partie, prenons comme exemple, l’authentification de l’API REST de Twitter.

Lorsque vous commencez avec une API, il est très important de lire attentivement et comprendre profondément la documentation. L’authentification est l’un des aspects où les développeurs se plantent souvent. L’une des causes est une mauvaise lecture de la documentation. Si vous avez l’habitude de travailler avec des API REST alors vous pourriez directement sauter à la section Authentification. Pour le cas de Twitter, il est aisé de manquer la ligne de la documentation qui dit que vous devez inclure dans la section body de votre requête la chaîne de caractère grant_type=client_credentials. Manquer de l’inclure résulterait à un échec complet, même si tout le reste de votre code est parfait. Assurez-vous toujours d’avoir bien lu et compris la documentation. Après l’avoir fait pour le cas de Twitter, vous pourrez construire un requête POST comme celle ci, qui génère un jeton d’accès :

$key = base64_encode( urlencode( "PKI865f6uvGZA6xvFTtb8IAA:i4pmOV0duXJEgty95Ghth89dh5wDIqfJOovKjs92ei878" ) );
$request = wp_remote_post('https://api.twitter.com/oauth2/token', array(
    'headers' => array(
        'Authorization' => 'Basic ' . $key,
        'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
    ),
    'body' => 'grant_type=client_credentials',
    'httpversion' => '1.1'
));
$token = json_decode( $request['body'] );
echo "<pre>"; var_dump($token); echo "</pre>";

La première des choses est d’encoder un jeton d’accès et une chaîne secrète (ceux que vous voyez ne sont pas valides). Ensuite formuler la requête proprement dit. Vous voyez qu’ici, selon les recommandations de Twitter on a ajouter deux headers Authorization et Content-Type, nous avons inclu la chaine grant_type=client_credentials et httpversion. Sans tout cela, nous ne pourrions pas générer le jeton d’accès indispensable pour effectuer les prochaines requêtes sur l’API de Twitter. Résultat :

wp-http-api-twitter-token

Maintenant que vous avez votre jeton d’accès, il est de bonne mise de le mettre en cache, car il est valide pour un bon moment, et le récupérer depuis l’API REST de Twitter pour chaque requête ne fera pas de bien à votre code. La notion de transients correspond bien à ce scénario, mettons la en œuvre.

$token = get_transient( 'twitter_access_token' );
$token = ( empty( $token ) ) ? get_twitter_access_token() : $token;
$request = wp_remote_get('https://api.twitter.com/1.1/followers/ids.json?screen_name=<votre-username-twitter>&count=5', array(
    'headers' => array(
        'Authorization' => 'Bearer ' . $token,
        'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
    ),
    'httpversion' => '1.1'
));
$token = json_decode( $request['body'] );

Cette requête devrait récupérer 5 de vos followers si vous remplacez <votre-username-twitter> par votre nom d’utilisateur Twitter. Dans ce code, on récupère notre jeton d’accès depuis un transient. Si ce dernier n’y est pas, on utilise la fonction get_twitter_access_token (que vous pouvez concevoir à partir de notre précédent exemple). Notez que cette fonction devra ajouter le jeton d’accès dans un transient.

Les fonctions utilitaires de l’API HTTP de WordPress

Il existe 4 fonctions qui permettent d’exécuter des requêtes. Ce sont wp_remote_get, wp_remote_post, wp_remote_head, wp_remote_request. La dernière est généralisée, c’est à dire que vous pouvez l’utiliser avec n’importe quelle méthode HTTP.

Il existe aussi 5 fonctions pour récupérer une partie d’une réponse. Ce sont wp_retrieve_body, wp_retrieve_header, wp_retrieve_headers, wp_retrieve_response_code, wp_retrieve_response_message.

Employez autant que possible les fonctions de l’API HTTP lorsque vous travaillez avec elle, pour que les autres développeurs puissent facilement comprendre votre code.

Le développement dans WordPress se dirige de façon cruciale vers une approche orientée API. Pour rester dans le bain, c’est le moment propice pour vous d’apprendre à utiliser les différentes API de WordPress.

Utilisez-vous déjà une API de WordPress ? Pourquoi et comment le faites vous ? Avez vous des astuces pour les rendre encore plus simples ? Partagez avec nous dans notre section des commentaires.