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 :

Activer l'API XML-RPC sous WordPress

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.

Authentificaiton à l'API WordPress

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 :

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.

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.

Nous utilisons l’extension PHP XML-RPC pour transformer notre requête en XML et notre réponse en Array PHP.

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.

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.

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.

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.

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.

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.

Les paramètres passés sont les suivants :

  1. blogid : Identifiant du site/blog sur lequel on requête
  2. login : identifiant de l’utilisateur connecté
  3. password : Mot de passe de l’utilisateur à identifier
  4. filter : Tableau de filtre parmi : post_type, post_status, number, offset, orderby et order
  5. 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.

wordpress-xmlrpc-posts

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 :

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 :

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 :