Mise à jour : Nouvelle API disponible avec WordPress 4.7
L’API de WordPress évolue avec WordPress 4.7. En effet, il n’est plus conseillé de passer par l’API XML-RPC présentée dans cet article.
Nous vous conseillons de lire cette article consacré à la nouvelle API REST de WordPress 4.7.
Comment fonctionne l’API de WordPress ?
Webservices : le protocole XML-RPC
WordPress dispose nativement d’une API distante de type XML-RPC. Le XML-RPC est un protocole RPC (Remote procedure call) basé sur un échange de messages XML sur du HTTP. Concrètement, cela revient à envoyer un XML en POST vers l’API qui répond à son tour en XML.
Si vous ne connaissez pas XML-RPC mais que vous avez déjà travailler avec d’autres formats de webservices comme SOAP ou REST, le principe reste assez proche.
Contrairement à SOAP, il n’y a pas de document WSDL pour vous indiquer les méthodes disponibles. Vous devrez donc lire la documentation pour avoir des informations sur le service.
En comparaison avec une architecture REST, l’URL du service ne change pas. En effet, le nom de la méthode que vous souhaitez contacter ne se trouve pas dans l’URL mais dans le content de votre requête. De même, vous n’avez pas à basculer entre GET, POST, PUT, PATCH, etc. Tout ce fait en POST et le type d’action est défini dans le XML.
Je vous ai déjà perdu ? Ne vous inquiétez pas, nous allons voir qu’il n’est pas nécessaire de connaitre le protocole XML-RPC pour l’utiliser car il suffit d’avoir une librairie ou une extension pour abstraire le protocole.
Activer l’API XML-RPC sur WordPress (WordPress <3.5)
Pour commencer, sachez que l’API est activée par défaut depuis WordPress 3.5. Vous avez donc aucun plugin à installer pour en profiter. Toutefois, si vous utilisez une version antérieure à là 3.5, vous devez l’activer dans les paramètres :
Maintenant que votre webservice est activé, il sera capable de traiter l’ensemble des demandes arrivant sur l’URL /xmlrpc.php de votre WordPress.
Gestion de l’authentification sur les webservices
Pour s’authentifier sur les webservices de WordPress, il suffit de disposer d’un compte utilisateur WordPress. La gestion des droits est donc la même que celle des utilisateurs. Nous vous conseillons de créer un profil et un utilisateur spécifique afin de contrôler tout ce qui sera fait à travers l’API. Cela permet d’avoir une vision claire des droits applicables à l’accès API et permet également de ne pas couper l’API si vous décidez de changer votre propre mot de passe.
Les 5 APIs : WordPress, Blogger, MetaWeblog, MovableType et PingBack
Cela peut sembler étrange mais WordPress dispose bien de 5 APIs. Depuis WordPress 3.4, l’ensemble des méthodes ont été regroupées sous une API principale mais le CMS embarque toujours des API spécifiques permettant à certains logiciels de s’interconnecter facilement. Par exemple, Windows Live Writer utilise l’API MetaWeblog pour récupérer et publier des articles.
Si votre WordPress est à jour, vous ne devriez avoir besoin que de l’API WordPress car elle couvre l’ensemble des autres API.
Voici la liste des API WordPress :
- Blogger API (Documentation | Spécification) – WordPress 1.5
- MetaWeblog API (Documentation | Spécification) – WordPress 1.5
- MovableType API (Documentation | Spécification) – WordPress 1.5
- PingBack API (Documentation | Spécification) – WordPress 1.5
- API WordPress (Documentation API WordPress) – WordPress 3.4
Vous trouverez ci-dessous l’ensemble des méthodes gérées par l’ensemble des APIs. Cette liste est issue du code source de WordPress.
WordPress API
wp.getUsersBlogs
wp.newPost
wp.editPost
wp.deletePost
wp.getPost
wp.getPosts
wp.newTerm
wp.editTerm
wp.deleteTerm
wp.getTerm
wp.getTerms
wp.getTaxonomy
wp.getTaxonomies
wp.getUser
wp.getUsers
wp.getProfile
wp.editProfile
wp.getPage
wp.getPages
wp.newPage
wp.deletePage
wp.editPage
wp.getPageList
wp.getAuthors
wp.getCategories
wp.getTags
wp.newCategory
wp.deleteCategory
wp.suggestCategories
wp.uploadFile
wp.deleteFile
wp.getCommentCount
wp.getPostStatusList
wp.getPageStatusList
wp.getPageTemplates
wp.getOptions
wp.setOptions
wp.getComment
wp.getComments
wp.deleteComment
wp.editComment
wp.newComment
wp.getCommentStatusList
wp.getMediaItem
wp.getMediaLibrary
wp.getPostFormats
wp.getPostType
wp.getPostTypes
wp.getRevisions
wp.restoreRevision
Blogger API
blogger.getUsersBlogs
blogger.getUserInfo
blogger.getPost
blogger.getRecentPosts
blogger.newPost
blogger.editPost
blogger.deletePost
MetaWeblog API
metaWeblog.newPost
metaWeblog.editPost
metaWeblog.getPost
metaWeblog.getRecentPosts
metaWeblog.getCategories
metaWeblog.newMediaObject
metaWeblog.deletePost
metaWeblog.getUsersBlogs
MovableType API
mt.getCategoryList
mt.getRecentPostTitles
mt.getPostCategories
mt.setPostCategories
mt.supportedMethods
mt.supportedTextFilters
mt.getTrackbackPings
mt.publishPost
PingBack
pingback.ping
pingback.extensions.getPingbacks
Demo
demo.sayHello
demo.addTwoNumbers
Comment interroger l’API de WordPress ?
Maintenant que vous savez ce qu’est l’API WordPress, voyons maintenant comment l’utiliser. Commençons par installer l’extension PHP XML-RPC qui nous permettra de retranscrire nos requêtes et nos réponses en XML.
|
1 |
apt-get install php5-xmlrpc |
Nous pouvons maintenant développer une petite fonction réutilisable permettant de s’abstraire dans la complexité de XML-RPC et de l’API de WordPress. Cette fonction a pour rôle de contacter le webservice de WordPress pour exécuter à distance une méthode avec les paramètres passés.
|
1 2 3 4 |
<?php function call($url, $method, array $params=[]){ /* ... */ } |
Nous utilisons l’extension PHP XML-RPC pour transformer notre requête en XML et notre réponse en Array PHP.
|
1 2 3 4 5 6 7 8 9 10 11 |
<?php function call($url, $method, array $params=[]){ // Build XML request $request = xmlrpc_encode_request($method, $params); /* ... */ // Parse result to get value return xmlrpc_decode($response, 'UTF-8'); } |
Il ne reste plus qu’à envoyer notre XML vers l’API. Pour cela, nous pourrions utiliser l’extension cURL mais nous allons le faire nativement avec un simple file_get_contents que l’on détourne pour faire du POST grâce à un contexte de flux.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
<?php function callApi($url, $method, array $params = []) { // Build XML request $request = xmlrpc_encode_request($method, $params); // Send request to WordPress $result = file_get_contents($url, FALSE, stream_context_create([ 'http' => [ 'method' => 'POST', 'header' => [ 'Content-type: application/x-www-form-urlencoded;charset=UTF-8', 'Content-Length: ' . mb_strlen($request) , ], 'content' => $request ] ] )); // Parse result to get value return xmlrpc_decode($response, 'UTF-8'); } |
Nous sommes maintenant prêt à interroger notre API. Utilisons l’API de démo pour vérifier que notre webservice fonctionne correctement. La méthode demo.sayHello ne demande aucun paramètre, nous avons donc besoin de l’URL et du nom de la méthode.
|
1 2 |
$url = 'https://blog.wixiweb.fr/xmlrpc.php'; echo callApi($url, 'demo.sayHello'); |
Hello!
Exemples d’utilisation de l’API WordPress
Nous pouvons utiliser notre fonction callApi() pour interroger WordPress à distance. Voyons maintenant quelques exemples pour bien comprendre les différents types de demandes que nous devons gérer.
Appeler une méthode avec des paramètres
Nous pouvons utiliser l’API de demo pour tester l’appel à une méthode nécessitant des paramètres. La méthode demo.addTwoNumbers permet de faire une addition et nécessite deux paramètres. Nous avons donc besoin de l’URL, du nom de la méthode et d’un tableau de paramètres.
|
1 2 |
$url = 'https://blog.wixiweb.fr/xmlrpc.php'; echo '10 + (-3) = ' . callApi($url, 'demo.addTwoNumbers', [10, -3]); |
10 + (-3) = 7
Appeler une méthode en s’authentifiant
Quittons l’API de demo pour passer à une méthode nécessitant une authentification sur l’API de WordPress. La méthode wp.getUsersBlogs permet de récupérer l’ensemble des sites et webservices accessibles par l’utilisateur connecté. Nous avons donc besoin de l’URL et d’un compte utilisateur.
|
1 2 3 4 |
$url = 'https://blog.wixiweb.fr/xmlrpc.php'; $login = 'arnaud.lemercier.me'; $password = 'rouen'; var_export(callApi($url, 'wp.getUsersBlogs', [$login, $password])); |
Vous pouvez voir que dans le cas d’un appel avec authentification, il suffit de passer le login et le mot de passe comme 1er et 2e valeur de notre tableau de paramètres.
Appeler une méthode de blog en s’authentifiant
Maintenant que nous avons vu comment récupérer la liste des sites/blogs accessibles, voyons maintenant comment appeler une méthode sur l’un de ces blogs. Le requête avec authentification et sélection de blog sont les plus courantes. Essayons de récupérer la liste des utilisateurs d’un blog.
|
1 2 3 4 5 |
$url = 'https://blog.wixiweb.fr/xmlrpc.php'; $login = 'arnaud.lemercier.me'; $password = 'rouen'; $blogid = 1; var_export(callApi($url, 'wp.getUsers', [$blogid, $login, $password])); |
Vous pouvez voir que dans le cas d’un appel avec authentification et séléction du blog, les paramètres sont blogId, Login, Password.
Comment récupérer des articles à partir de l’API WordPress ?
Maintenant que vous avez vu tous les types de requêtes possibles, voyons comment récupérer les articles/posts d’un blog en appliquant quelques filtres de recherche. Nous allons faire un requête avec sélection du blog, authentification et passage de paramètres.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
$url = 'https://blog.wixiweb.fr/xmlrpc.php'; $login = 'arnaud.lemercier.me'; $password = 'rouen'; $blogid = 1; // Get posts $posts = callApi($url, 'wp.getPosts', [ $blogId, $login, $password, ['post_status' => 'publish'], ['post_author', 'post_excerpt', 'post_title', 'link'] ]); print_r($posts); |
Les paramètres passés sont les suivants :
- blogid : Identifiant du site/blog sur lequel on requête
- login : identifiant de l’utilisateur connecté
- password : Mot de passe de l’utilisateur à identifier
- filter : Tableau de filtre parmi : post_type, post_status, number, offset, orderby et order
- fields : Tableau de champs à récupérer parmi : post_id, post_title datetime post_date, datetime post_date_gmt, datetime post_modified, datetime post_modified_gmt, post_status, post_type, post_format, post_name, post_author, author id, post_password, post_excerpt, post_content, post_parent, post_mime_type, link, guid, menu_order, comment_status, ping_status, sticky, post_thumbnail, terms, custom_fields, id, key, value, enclosure, url, length, type
Etude de cas : Afficher les derniers posts sur un autre site
Voyons maintenant un cas concret d’utilisation de l’API pour récupérer les derniers articles WordPress publiés sur le blog de Wixiweb afin de les afficher sur mon site web personnel.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 |
<?php $url = 'https://blog.wixiweb.fr/xmlrpc.php'; $login = 'arnaud.lemercier.me'; $password = 'rouen'; $blogid = 1; // Get posts $posts = callApi($url, 'wp.getPosts', [ $blogId, $login, $password, ['post_status' => 'publish'], ['post_id', 'post_author', 'post_excerpt', 'post_title', 'link', 'post_thumbnail', 'post_status', 'post_date'] ]); ?> <?php foreach ($posts as $post) :?> <div class="post"> <h2><a href="<?= $article->link?>"><?= $article->post_title?></a></h2> <div class="post-content"> <a href="<?= $article->link?>"> <img src="<?= $article->post_thumbnail->thumbnail?>"> </a> <div><?= $article->post_excerpt?></div> </div> <div><?= date_format(date_create($article->post_date->scalar), 'd/m/Y'); ?></div> </div> <?php endforeach; ?> |
Les articles récupérés sont affichés dans le HTML avec un simple foreach. Il ne reste plus qu’à améliorer la fonction d’appel en y ajoutant une gestion de cache, une gestion d’erreur réseau ou de formatage XML, etc.
Comment étendre l’API WordPress ?
Pour aller plus loin, voyons comment enrichir l’API native de WordPress avec des nouvelles méthodes. Vous pouvez étendre l’API afin d’y ajouter des fonctionnalités, implémenter des méthodes liées à vos Custom Post Types et vos Custom Post Fields, mettre à niveau l’API par rapport à vos surcharges WordPress, rendre accessible des fonctionnalités de vos plugins à travers l’API, etc.
Création d’un plugin WordPress
Nous allons créer un plugin qui va ajouter la méthode wixiweb.hi à l’API de WordPress. Cette méthode retournera simplement « Bonjour Wixiweb ! ». Voici le code de notre plugin :
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 |
<?php /** * Plugin Name: Wixiweb XML-RPC API Extended * Plugin URI: http://wixiweb.fr * Description: Nouvelles méthodes de l'API XML-RPC de Wordpress * Author: Arnaud Lemercier * Version: 1.0 */ class WixiwebXmlrpcExtended { public function __construct() { add_filter('xmlrpc_methods', function($methods) { // Déclare une nouvelle méthode $methods['wixiweb.hi'] = ['WixiwebXmlrpcExtended', 'hi']; return $methods; }); } /** * Method wixiweb.hi * @return String */ public function hi() { return "Bonjour Wixiweb !"; } } new WixiwebXmlrpcExtended(); |
Comme vous pouvez le voir, nous allons simplement utiliser le filtre xmlrpc_methods pour brancher notre méthode hi().
Méthode avec paramètres et gestion d’erreur
Voici un autre exemple de plugin un peu plus avancé. Nous proposons une méthode wixiweb.div qui fait une division avec les deux valeurs passées en paramètre. Nous voyons comment gérer des paramètres et également comment gérer une erreur au niveau de l’API :
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
<?php /** * Plugin Name: Wixiweb XML-RPC API Extended * Plugin URI: http://wixiweb.fr * Description: Nouvelles méthodes de l'API XML-RPC de Wordpress * Author: Arnaud Lemercier * Version: 1.0 */ class WixiwebXmlrpcExtended { public function __construct() { add_filter('xmlrpc_methods', function($methods) { // Déclare une nouvelle méthode $methods['wixiweb.div'] = ['WixiwebXmlrpcExtended', 'div']; return $methods; }); } /** * Method wixiweb.div * @param array $params * @return Int */ public function div($params) { // Extract params list($a, $b) = $params; // Errors handler if ($b == 0) { return new IXR_Error( 600, __( 'Division par 0 impossible' ) ); } return $a / $b; } } new WixiwebXmlrpcExtended(); |
On utilise la fonction list() de PHP pour extraire les paramètres et les distribuer dans des variables. La gestion d’erreur de l’API s’effectue à l’aide de la classe IXR_Error qui se charge de formater le retour XML.
Les évolutions à venir : une API RESTful ?
Si comme moi vous vous demandez ce qui pourrait bien arriver dans les prochaines versions de WordPress, voici un début de réponse.
Un plugin nommé WP REST API est actuellement en cours de développement (version 2) et devrait être intégré au cœur de WordPress avant la fin de l’année si celui-ci est assez stable. Il est prévu pour être intégré directement à WordPress 4.5. Ce plugin officiellement listé comme Feature Plugin chez WordPress offrira donc une nouvelle API basée sur RESTFUL.
Si vous ne souhaitez pas attendre, sachez qu’il existe déjà une version stable de WP REST API mais que la version qui sera intégrée à WordPress sera différente. Si vous souhaitez réaliser des tests, la version de développement est disponible sur GitHub.
Si vous souhaitez suivre l’actualité de cette fonctionnalité majeure, je vous invite à suivre le blog des contributeurs WordPress, le blog officiel de la REST API TEAM et de venir échanger sur le Slack WordPress #core-restapi.
Notez bien que ce plugin est en pleine refonte avant d’être intégré. Pour vous en rendre compte, vous pouvez comparer la documentation de la version 1 stable et celle de la future version 2 en cours de développement :
- http://wp-api.org/ (version stable)
- http://v2.wp-api.org/ (prochaine version)
Salut, billet assez complet. Je me permets de glisser ma petite contribution WP http://fr.tuto.com/wordpress/decouvrir-l-api-json-rest-de-wordpress-wordpress,47758.html elle permettra à ceux qui veulent découvrir l’API Json REST de WordPress de se faire une idée précise de ce qui les attends :)
J’ajouterais quelques points à cette démonstration :
– XML RPC c’est pratique en effet pour connecter WordPress à d’autres softs (pas besoin de dév une interface), ça peut trouver d’autres utilités notamment du remote publishing avec des méthodes prédéfinies
– Certaines installations l’ont en revanche tout simplement banni suite à des attaques de type DDos, y avait du SSRF aussi je crois, il y a même un plugin qui s’appelle « Disable XML-RPC », y en a qui mettent une 403 aussi via le .htaccess directement côté serveur. Sinon ça tient en un filtre => add_filter(‘xmlrpc_enabled’, ‘__return_false’)
– à noter la constante XMLRPC_REQUEST qui permet de différencier les requêtes XML-RPC des requêtes HTTP classiques
Après question de goût mais moi je préfère nettement le JSON comme format que le XML c’est pourquoi cette API REST, même si elle tarde un peu à venir, promet notamment pour s’ouvrir, enfin, aux autres développeurs.
Salut Julien,
Merci pour tes remarques. Tu as raison de rappeler que, tout comme l’interface d’administration, l’API est un accès qui peut être la source d’attaque. Malheureusement, je ne comprends pas pourquoi cette fonctionnalité, qui est utilisée que dans des cas bien précis, est activée par défaut. Pour ma part, je conseille de créer un compte dédié à l’API et d’y mettre un très grand mot de passe. De plus, pas besoin d’un compte administrateur si vous n’avez pas besoin de l’ensemble des méthodes.
Je te rejoins également sur le JSON. C’est évident que dès que l’API RESTFUL sortira nativement, elle remplacera cette API XML-RPC pour l’ensemble des futurs développements.
N’hésites pas à revenir partager des infos sur ce sujet ;-)
@arnaud https://core.trac.wordpress.org/ticket/21509 parce qu’ils on considéré qu’il n’y avait plus de raison objective de mettre l’activation en tant qu’option.
Bonjour,
Je suis une grosse tanche en PHP (j’ai eu dans le passé quelques notions de asp) et, du coup, évidemment je ne parviens pas à faire marcher l’api de démo WordPress… Cet article etant magnifiquement simple et clair, je me demandais si je pouvais avoir un peu d’aide ici…
Bref, j’ai un site hebergé par OVH et un blog WP hebergé chez WordPress. J’ai placé dans .htaccess de mon site le script SetEnv PHP_VER 5_4. Déja, dans cette config, l’utilisation de l’API est-elle possible ?
En admettant que oui, j’ai créé un fichier api.php dans lequel j’ai écrit les fonctions call et callapi dans le header. L’appel demoapi a été placé dans un de mon .
En consultant la page http://www.monsite.fr/api.php, mon navigateur m’affiche
[[ 'method' => 'POST','header' => [
'Content-type: application/x-www-form-urlencoded;charset=UTF-8',
'Content-Length: ' . mb_strlen($request)
],
'content' => $request
]]
));
// Parse result to get value
return xmlrpc_decode($response, 'UTF-8'); } ?>].
Pas de Hello Word en vu…
Aux bonnes ames charitables, merci de votre aide :)
Bonjour,
Si votre PHP s’affiche c’est qu’il n’est pas interprété.
Vous devez commencer votre fichier par la balise
Je n'ai malheureusement pas assez d'information pour vous en dire plus sur votre problème.
Bonjour Arnaud,
Désolé de cette réponse tardive. Merci de votre aide.
En fait, il semble que je ne puisse rien faire pour corriger mon problème… Mon blog est hébergé sur un plan gratuit qui bloque certaines URL dont celle du plugin WP API REST. Donc pas moyen de le faire marcher.
Merci encore pour votre aide et félicitations pour votre site.
Bonjour Arnaud,
Merci beaucoup pour cet article, il est vraiment très clair, j’arrive maintenant à créer des articles « à distance « via l’API :-)
J’essaie maintenant d’aller plus loin en intégrant automatiquement des images, mais ça ne fonctionne pas. J’utilise le code suivant :
$method = ‘wp.uploadFile’;
$donnees = array(‘name’ => ‘test.jpg’,
‘type’ => ‘image/jpeg’,
‘bits’ => base64_encode(file_get_contents(‘../Images/nougat.jpg’));
var_export(callApi($url, $method, [0, $login, $motdepasse, $donnees]));
Un fichier est bien ajouté à la bibliothèque de médias de WordPress mais il est illisible. Il semble être corrompu.
J’ai testé plein d’alternatives et j’ai consulté divers forums sans trouver de réponses, pourriez-vous m’aider ?
Merci d’avance pour votre réponse :-)
Bonjour
Merci beaucoup pour votre article. C’est un peu long mais intéressant. Je crois que plusieurs personnes seront satisfaites de toutes les informations que vous nous aviez apportées.
[…] savoir + sur l’API XML-RPC de WordPress En savoir + sur l’API-REST de […]