Tout savoir sur WordPress

A la découverte de l’API Rest WordPress

Résumé de ma conférence à propos de l’API Rest WordPress au WP Tech 2015 à Nantes. Qu’est-ce qu’une API Rest ? Comment fonctionne l’API Rest WordPress ? Pour quelles utilisations ? Que va changer l’API dans un futur proche…

J’ai eu l’honneur de présenter l’API Rest au WP Tech cette année, pile au moment où cette API s’apprête à voir le jour dans le core WordPress, et juste après les annonces de Calypso. En simultanée au WordCamp US,Matt Mullenweg annonce à tout le monde qu’il est temps de passer au Js sur WordPress.

Les slides de ma conférence sont disponibles ici :

En attendant la vidéo voici le détail de ma conférence, en deux parties :

  • Article pour comprendre l’API, ses enjeux, et l’avenir de WordPress
  • Tutoriel pour mettre en place l’API et l’utiliser.

Bonne lecture !

Qu’est-ce qu’une API Rest ?

Capture d’écran 2015-12-07 à 11.22.45

Une API Rest c’est la capacité de communiquer avec un site ou une application depuis un autre site. C’est une ouverture afin de rendre possible la communication de données entre applications.

l’API rest se caractérise par l’envoi d’une requête HTTP sous forme d’un schéma URL contenant les commandes que l’on souhaite, et la réponse est renvoyée en JSON (Javascript Object Notation) ou parfois le format XML.

Afin de sécuriser les échanges, le fournisseur de l’API vous octroie une clé d’API unique.

Comment se présente une requête API ?

Voici par exemple une requête GET (= on veut récupérer des données) sur l’API twitter :

requete api

Cette URL demande à l’API d’afficher les 2 derniers tweets du compte @twitterapi. Une API est toujours accompagnée d’une documentation. Vous trouverez des APIs de partout (twitter, facebook, flicker….)

Voici un exemple de résultat JSON renvoyé :

résultat json

Comment lancer des requêtes API ?

Vous pouvez dans le plus simple des cas taper l’URL directement dans votre navigateur et voir le résultat apparaitre. Il est possible de lancer des requêtes HTTP depuis tous les langages de programmation. En javascript, vous pourrez faire une requête AJAX et récupérer, interpréter le résultat et l’afficher à l’écran facilement.

L’histoire de la WP API Rest

histoire WP API REST

L’histoire de l’API Rest commence en 2013 :

  • 2013 : Projet lancé lors du GSOC par Ryan McCue, core dev WP (chez HumanMade depuis 2014 – Happytables)
  • Mai 2014 : Version 1.0 beta release
  • Mars 2015 : V1.2 beta avec beaucoup de nouveautés
  • 29 Avril 2015 : V2.0 Beta : changement de routes
  • 21 septembre 2015 : Merge proposal
  • 28 octobre 2015 : Merge dans le Core WP
  • 8 décembre 2015 : Sortie de WP 4.4 avec l’API phase 1
  • Première moitié 2016 : API Rest phase 2 (API exposée vers l’extérieur)

Comme toujours dans le bâtiment et le web, il y a du retard.

L’api était initialement prévue pour WP 4.1, puis 4.3 en aout 2015…

Source : https://make.wordpress.org/core/tag/json-api/

Selon Brian Krogsgard, de Poststatus.com, l’API Rest est pour lui le projet le plus excitant depuis l’apparition des custom post types dans WordPress.

Toujours selon lui, l’intégration de l’API REST marquera la transformation finale de WP en un véritable CMS, qui ne sera définitivement plus attaché à ses humbles racines de plateforme de blog.

Remi Corson m’indiquait sur twitter que WooCommerce disposait déjà d’une API REST fort bien utile.

Et le XML-RPC dans tout ça ?

WordPress disposait déjà d’une interface de liaison avec d’autres applications, appelée XML RPC. Mais cette interface est limitée, communique en XML plutôt que JSON et ne permet pas autant de choses que l’API Rest.

Comment l’API Rest va changer WordPress ?

Quelques idées et futures révolutions auxquelles s’attendre…

1. Des thèmes complètement basés en JS

Ils pourront se passer du moteur de template, être complètement gérés en Js avec l’aide de React JS par exemple.

Un thème expérimental proposé par Automattic : https://github.com/Automattic/Picard que vous pourrez essayer ! Il reste du chemin à parcourrir mais les bases sont posées. La révolution en marche. Au WordCamp US Matt a indiqué clairement que le JS était l’avenir de WordPress et tout le monde devrait s’y mettre.

Si vous voulez vous y essayer, je vous conseille ce tuto sur themeshaper.com.

2. des applications Single page

les SPA (Single Pages Apps) sont des applications codées en Javascript qui fonctionnent sans rechargement complet de page, plus rapides donc à charger et plus réactives. On se passe donc de PHP et compagnie au profit de JS (React encore, ou des librairies comme ionic, meteor…)

WordPress peut servir de base applicative, voici un exemple d’application réalisable avec WordPress :

single page app

Cet exemple d’app est une étude de cas intéressante que vous pourrez consulter ici. C’est fictif bien sûr mais j’y verrais bien fait avec un WordPress.

En résumé WP servirait de base applicative (tant que l’application a pour but de diffuser de l’information un minimum), et en se basant sur le theming en JS, peut proposer une interface complètement réactive.

3. Nouvelle interface administrateur à terme ?

L’admin WordPress a tendance à être un peu lente, surtout sur les gros sites. Automattic, la société derrière wordpress.com a décidé de refaire complètement son interface backend avec du Node.js + l’API Rest.

Si vous avez un site wordpress.com vous avez déjà cette nouvelle interface. Vous pourrez la tester sur votre site en installant jetpack et en créant un compte wp.com

calypso wordpress

4. Applications natives mobiles

L’utilisation la plus fréquente sera la création d’applications mobiles natives iOs et Android récupérant les données du site via l’API Rest afin de les afficher dans l’app.

Nous avons pu le mettre en application très tôt avec notre client goldenmoustache.com , et ça fonctionne super bien !

api apps natives

Les applications natives Golden Moustache pour iOs et Android utilisent l’API Rest WP pour récupérer les derniers articles, auteurs…

5. Un backend CMS Mobile

Dans la lignée du point précédent, il serait possible de créer un service permettant aux éditeurs d’apps mobiles de leur fournir la puissance de WordPress pour éditer le contenu de leurs apps. C’est ce que fait Contentful, mais il ne le font pas avec WordPress. Il y a donc une opportunité de business là dessous, je vous le dit !

contenful backend cms wp like

6. Des panneaux d’administrations spécialisés et personnalisés

Les besoins devenant de plus en plus larges et plus spécifiques, le panneau d’admin de WordPress de demain sera peut-être à adapter en fonction des besoins de ses utilisateurs. Imaginons un restaurant : le site permettrait d’afficher le menu, des actualités sur le blog, mais aussi prendre des réservations et gérer les commandes, le placement aux tables…

Le serveur n’aurait pas besoin de toute l’interface WP, simplement consulter les réservations et l’assignation aux tables. Dans ce cas un panneau d’administration spécial (avec l’UX qui va avec) pourrait être une bonne idée.

custom panel

7. Intégration de news sur des applications Ruby, Python…

L’API permettrait également, sur n’importe quelle plateforme codée en Ruby, Python, C… d’intégrer les dernières news. Cela permettrait d’intégrer WordPress n’importe où en toute facilité. Cela permettrait également plus de lattitudes qu’une simple intégration RSS.

integrer news plateforme

8. Un éditeur de contenu front-end

Les éditeurs de contenu front-end sont de plus en plus en train de pointer le bout de leur nez. L’API va simplifier tout leur process et permettra de mettre à jour et créer des données WP en toute simplicité, ce qui devrait simplifier leur code et faciliter leur intégration.

editeur front

Javascript a explosé, et nous devrions tous s’y mettre

Javascript a connu une explosion depuis jQuery.
Aujourd’hui on retrouve de nombreuses librairies JS : Node.js, Angular, Backbone, Ember, React, meteor, ionic… et j’en passe !

L’équipe derrière WP l’a bien compris : WordPress doit passer le pas de Javascript et l’API Rest va l’aider !

On a un peu l’impression en ce moment que les développeurs sont vus de cette manière :

dev php versus dev js

 L’API REST WP, Comment ça marche ?

L’installation !

Pour utiliser toutes les fonctions, vous devez télécharger le plugin API (si vous lisez ceci après mi 2016, normalement ce n’est plus nécessaire)

plugin api rest

 

Envoyer des requêtes

Testez directement dans le navigateur les requêtes suivantes (en remplaçant bien sur par le nom de votre site).

Pour le moment la dernière ne devrait pas fonctionner (ou du moins afficher la même chose qu’avec /posts/)

requetes url

Le principe est simple, vous ciblez d’abord le custom post type (page, post, autre…) et vous y ajoutez des paramètres : le nombre de résultats par page, la page (1,2,3…) et enfin, le plus important, des filtres qui s’avèrent être les mêmes que la WP Query.

Consultez donc le Codex, rubrique WP Query pour voir toutes les possibilités : WP Query Codex.

Le résultat apparait à l’écran :

résultat json

On y trouve : l’ID de l’article, la date de publication, le GUID, la date de modification, le slug, le post type, le lien, le titre, le contenu, l’auteur… Pratique !

Sécurité et authentification

Afin de sécuriser l’API pour éviter que tout le monde s’amuse avec, il existe 2 méthodes :

1. Authentification Nonce pour les développeurs d’extensions et de thèmes

Pour développer un thème ou une extension, le passage d’un Nonce est suffisant, voici le code à déclarer dans functions.php pour passer la valeur du nonce côté front :

// Ajouter les scripts

function forapi_scripts() {

	if(is_page(27)):
		// Charge mon script perso
		wp_enqueue_script( 'wpapitest', get_template_directory_uri() . '/wpapitest.js', array(), '1', true );
		
		// envoie le Nonce + l'url ROOT de l'API en frontend
		wp_localize_script( 'wpapitest', 'WP_API_Settings', array( 'root' => esc_url_raw( rest_url() ), 'nonce' => wp_create_nonce( 'wp_rest' ) ) );
	
	endif;
}
add_action( 'wp_enqueue_scripts', 'forapi_scripts' );

Dans votre script.js, vous pourrez envoyer le nonce dans le header de la requête afin de l’authentifier.

(function($) {
$(document).ready(function(){
  
  var baseURL = WP_API_Settings.root;
  baseURL = baseURL+"wp/v2";

  // Send request
    $.ajax({
      url: url,
      beforeSend: function( xhr ) {
        // Important : authenticate user to grant access to all WP API ENDPOINT
        xhr.setRequestHeader('X-WP-Nonce', WP_API_Settings.nonce);
      }
    })
    .done(function( data ) {
      var $r = $("#result");
      
      $r.html( htmlEncode(JSON.stringify(data, undefined, 2)));
      //console.log(JSON.stringify(data, undefined, 2));
      
      $(".updated").fadeIn(function(){
        setTimeout(function(){
          $(".updated").fadeOut();
        }, 1500);
      });
    });
  }

});
})(jQuery);

Et voilà ! vous pouvez utiliser l’API Rest comme bon vous semble désormais !

2. Authentification Oauth pour l’extérieur

Pour accéder à l’API de l’extérieur, par exemple depuis un autre site ou depuis une application mobile, il conviendra de mettre en place une authentification Oauth. Il faudra installer Oauth sur votre serveur hébergeant le site, ainsi que le plugin Oauth pour WordPress (qui sera à terme intégré à l’API WP en natif).

Hooks et filters pour aller plus loin

hooks filters API rest WP

Débloquer certains filtres

Certains filtres sont bloqués par défaut mais on peut les autoriser.
Parmi eux : les meta_queries, les data_queries…

Voir le tutoriel

Envoyer les customs fields à l’API

Par défaut l’API n’envoie pas le contenu des custom fields. Il est possible d’envoyer n’importe quelle donnée supplémentaire grâce à un hook.

Voir le tutoriel

Prise en charge des Custom Post Types

Vous pourrez simplement exposer vos Custom Post Types (CTP) à l’API lors de la déclaration de ceux-ci.

Voir le tutoriel

Créez vos propres routes API

C’est très simple de créer vos propres routes. D’ailleurs dans WP 4.4, l’API n’est intégrée qu’en phase 1 : aucune route n’est exposée par défaut et vous devrez les créer vous même en attendant la version définitive.

Voir le tutoriel

Namespaces

afin d’éviter tout conflit, vous pouvez créer votre propre namespace, qui se traduira par un changement dans l’URL. Au lieu de /wp/v2 vous pouvez définir myplugin/v1.

 

Il y a un souci avec le web dynamique !

C’est un problème de WordPress, mais lorsque l’on utilise des pages, on ne le voit pas : si entre 2 consultations de page l’auteur ajoute un article, lorsque j’afficherais la page 2, je reverrais le dernier article de la page un, reléguée à la page suivante.

Sur une application single page, ou une application mobile, l’article en question apparaitra 2 fois de suite. Pas top. Mais la solution s’avère très simple :

Voir le tutoriel

dynamique probleme

Ressources utiles

Voici des liens très utiles si vous souhaitez en savoir plus sur l’API Rest de WordPress :

Documentation : http://v2.wp-api.org/

Repo Git Hub :https://github.com/WP-API/WP-API

Discussion Core : https://make.wordpress.org/core/tag/json-api/

Plugin Homepage : https://wordpress.org/plugins/json-rest-api/

Articles :
https://poststatus.com/wordpress-json-rest-api/
https://premium.wpmudev.org/blog/wordpress-rest-api/
http://torquemag.io/on-the-wordpress-rest-api-reflecting-on-the-past-and-looking-to-the-future/

Tutos :
http://themeshaper.com/2015/11/27/challenges-javascript-theming/

Conférences :
http://jacklenox.com/2015/03/30/building-themes-with-the-wp-rest-api-wordcamp-london-march-2015/

 

 

Et voilà ! J’espère que cet article vous a plu !

Cet article a été mis à jour il y a 504 jours - Il n'est peut être plus à jour !

Article écrit par Maxime BJ

Développeur, bloggeur et formateur Web spécialisé WordPress. 31 ans. Grenoblois. Co-fondateur de WPChef, l’organisme de formation WordPress.

Organisateur de WPInAlps, le meetup WordPress Grenoblois. Vous pouvez me rencontrer lors d’événements tels que WordCamp Paris et Europe. Traducteur Français de l’extension Advanced Custom Fields. Également développeur d’applications web avec MeteorJs. Je m’occupe un site pour apprendre l’informatique aux débutants gratuitement.

J’aime les jeux vidéo, la rando, la bouffe bien grasse et les voyages.

8 Commentaires

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *

  1. Bonjour

    Excellent article :-)

    Question du développeur… DotNet que je suis (!) car aujourd’hui, l’une des principales difficultés que j’ai est de faire le lien entre mes applications de gestion de contenu (développements WinForms, en gros du client lourd en VB.Net / SQL Server) et les sites support éventuels, sous WordPress.

    L’API Rest permettrait donc d’aller (beaucoup) plus loin que XML RPC en termes de diffusion de contenus ?

    • Concrètement tu peux appeler toutes les actions de WP via l’API (en lecture comme en écriture) donc oui c’est très complet et ça permettrait en théorie de complètement se passer du front WP et même du back, réduisant WP à un système de stockage d’articles s’il le fallait

  2. Bonjour et merci pour cette article très fourni ! J’ai une question sur l’authentification : je travail sur une appli Angular2 et je n’arrive pas à configurer une clé avec les extension Oauth, pourrais-tu expliquer rapidement comment ça se configure ? Encore merci pour ton article ! Julien

    • C’est une bonne question malheureusement je ne suis pas allé aussi loin. Il est vrai que la configuration Oauth à l’air assez particulière à mettre en oeuvre

e1175a6b7ba1eeccb065b3dfceb86646************