Playing With
Pixels
and Building Stuff.

-

Introduction à
l'API JSON
de Wordpress

Le 18/05/2015

$(document).ready(function(){
    $.getJSON('wp-json/posts', function(json){
        // et hop json...
    });
});

Pour faire des blogs un peu spéciaux avec Wordpress, il y a déjà pas mal de possibilités "classiques" :

Pour aller encore plus loin, voire créer des web-apps basées sur Wordpress, il y a aussi une API officielle basée sur le format JSON.

Une API tellement officielle qu'elle fera peut-être partie intégrante de Wordpress un de ces 4. En attendant c'est un plugin comme les autres, à installer sur votre blog : Une fois le zip téléchargé, dézippé, et uploadé sur votre serveur, il faudra donc l'activer depuis l'admin, du côté des extensions.

Dès que le plugin est activé, vous avez alors une nouvelle porte d'entrée publique vers les contenus de votre blog : www.monblog.com/wp-json/

C'est donc d'une API qu'il s'agit, et vous allez devoir indiquer des paramètres pour récupérer le contenu dont vous avez besoin.
Et ce contenu vous sera servi brut, au format JSON.

Ensuite à vous de la traiter comme vous le souhaitez. Dans mon cas je m'en servirais bien en Javascript, et sans doute via jQuery. Les requêtes ressembleront donc à ça avec jQuery :

$(document).ready(function(){
	$.getJSON('wp-json/posts', function(json){
		// et hop json contient l'objet avec vos contenus
	});
});

La fonction getJSON() interprète directement le texte brut reçu pour en faire un objet Javascript... Pour ce que vous en faites par la suite, c'est une autre histoire, il vous faudra évidemment des connaissances en Javascript et en jQuery si vous choisissez cette stratégie.

Quoi qu'il en soit la documentation officielle est assez toufue (ce qui est plutôt bien), mais ce n'est pas évident de démarrer.

*---*

Voici donc quelques requêtes de base pour bien comprendre.

Récupérer toutes les données de tous les posts :

wp-json/posts

Récupérer les données d'un seul post, par son ID :

wp-json/posts/593

Vous voyez le principe. Quand je parle de "requête", il s'agit en fait juste d'une URL que vous pouvez même saisir manuellement dans votre navigateur pour tester. Le résultat n'est guère lisible, il vaut mieux récupérer ça en Javascript par exemple, dans une requête Ajax.

Là où ça devient intéressant, c'est qu'il y a une foule de paramètres qu'on peut combiner pour cibler du contenu, le trier, l'ordonner, le filtrer par page, etc

Filtrer les articles d'un catégorie :

wp-json/posts?filter[cat]=6
wp-json/posts?filter[category_name]=raspberry-pi

Dans ce dernier exemple, en fait ce n'est pas le nom de l'article mais son "slug" (le nom en version URL) qui est utilisé.

Filtrer par mot clé (faire une recherche, quoi) :

wp-json/posts?filter[s]=css3

Filtrer par id de post :

wp-json/posts?filter[p]=458

Filtrer les articles de la catégorie "pjs", ordonnés suivant le titre des articles (ordre croissant), en mode "2 articles par page", et seulement la page 1 des résultats :

wp-json/posts?filter[category_name]=pjs&filter[orderby]=name&filter[order]=ASC&filter[posts_per_page]=2&filter[nopaging]=true&filter[paged]=1

Plutôt cool, non ?

*---*

Voici une sélection des paramètres utiles à passer dans ?filter[...] :

author l'id d'un auteur
cat l'id d'une catégorie
category_name le "slug" d'une catégorie
category_in un Array d'ids de catégories
tag le "slug" d'un tag
tag_id l'id d'un tag
tag_in un Array d'ids de tags
p l'id d'un post unique
name le "slug" d'un post unique
page_id l'id d'une page
post__in un Array d'ids de posts, dans lesquels piocher les résultats (à combiner avec d'autres filtres)
post__not__in un Array d'ids de posts... à éliminer des résultats (en combinant)
post_type le type de post recherché : 'post', 'page', etc
posts_per_page le nb de posts demandés parmi ceux correspondants aux filtres
paged le n° de page de résultat souhaité (à combiner avec posts_per_page)
offset le nb de posts à éliminer des résultats (virer le deux 1ers par ex)
order 'ASC' ou 'DESC'
orderby 'ID', 'author', 'title', 'name' (= slug), 'type', 'date', 'modified', 'rand', etc

Il y a plein d'autres possibilités détaillées ici, ce sont les mêmes filtres que lors d'une requête classique en PHP : http://codex.wordpress.org/Class_Reference/WP_Query#Parameters

*---*

Pour finir, l'API offre encore d'autres filtres si vous êtes identifié, voire même la possibilité de créer / mettre à jour des contenus directement en JSON... bon, à priori ça demande un autre plugin : WP-API - Basic-Auth

Il est possible que j'aie à m'en servir sur un projet qui démarre, j'essaierai de documenter ça aussi.

Côté documentation officielle :