L'API de Wordpress : Introduction

L’API de WordPress : Introduction


WordPress propose nativement avec chaque installation une API REST JSON. Grâce à cette API, totalement repensée en 2016, vous pourrez accéder au contenu d’un site WordPress depuis n’importe où : un autre site web, une application iPhone, desktop, etc.

Il y a quelques années, avec la version 3.5, WordPress avait commencé à distribuer nativement une API XML-RPC. Désormais à la version 4.9, le leader du CMS propose depuis déjà quelques années une API REST JSON à ses utilisateurs. Ça fait beaucoup de termes barbares en une seule phrase. Alors voici quelques explications.

C’est quoi une API ?

Une API est une porte d’accès sur un système : elle vous permet de consulter et parfois modifier le contenu de la base de données d’un serveur distant. Cette porte d’entrée est contrôlée et les actions, filtres et paramètres dépendent des accès donnés par le développeur.

Dans le cas de WordPress, l’API vous permet de consulter le contenu principal d’un site (pages, articles, catégories, projets, etc.), mais aussi d’effectuer des modifications (ajouter, modifier, supprimer). Cette dernière option pourrait permettre l’ajout de contenu automatisée. Notons cependant qu’il est bien sûr nécessaire de s’authentifier pour effectuer des opérations de modification.

N’ayez donc aucune crainte : seul le contenu public déjà disponible aux visiteurs est accessible sans authentification.

À quoi peut servir l’API de WordPress ?

L’API de WordPress peut vous permettre d’accéder aux données d’un site géré avec WordPress. Comme ça, rien de bien excitant. Mais voilà quelques exemples concret d’utilisation :

  • Utiliser WordPress comme base de données, mais créer son site totalement librement. On évite la la rigidité du CMS et faire appel au contenu dont on a besoin par l’API. On peut également créé des thèmes WordPress avec des fonctionnalités supplémentaires, ainsi des modules sur cette base.
  • Utiliser WordPress comme un back office, un peu comme la proposition du dessus, mais pour application mobile ou desktop par exemple.
  • Permettre d’afficher du contenu cross-website. Comprendre qu’on accès au contenu d’un site A à partir d’un site B. C’est ce que je vais vous proposer de réaliser à l’issue de cette série d’articles.

Comment activer l’API de WordPress ?

En règle général l’API est déjà activée par défaut. Mais pour vous en assurer, il suffit d’activer la réécriture d’URL. Dans le menu Réglages > Permaliens, choisissez une autre option que Simple.

Activer les permaliens de WordPress

Pour vérifier que votre API fonctionne, tapez dans votre navigateur le nom de votre site, suivi de /wp-json (l’adresse de base de l’API) ce qui devrait vous donner quelque chose de ce genre :

Le contenu retourné est en JSON et si vous le consultez, vous pourrez constater qu’il s’agit d’une documentation pour utiliser l’API.

Effectuer des requêtes à l’API

Avant de commencer, je vous conseil de prendre le temps de consulter le manuel d’utilisation, en anglais, mis en ligne par le site officiel. Pour vous présenter l’API pas besoin de taper du code, vous pourrez exécutez toute ces requêtes comme si vous accédiez à un site Internet, en les tapant dans la barre d’adresse de votre navigateur.

Vous trouverez ici la liste des routes que vous pourrez exécuter avec l’API pour accéder au données d’un site. Les plus importantes :

/wp/v2/posts  : Recherche et manipulation des articles
/wp/v2/pages  : Recherche et manipulation des pages
/wp/v2/media : Recherche et manipulation des images, vidéos, documents, etc.

Prenons l’exemple de mon blog. Pour afficher la liste des articles du blog tapez simplement :

http://www.newslang.ch/wp-json/wp/v2/posts

Et hop :

À noter que par défaut, WordPress affiche les 10 premiers résultats uniquement. Vous pouvez forcer le nombre de résultat en spécifiant un paramètre per_page et en donnant le nombre de résultat que vous désirez par requête. En tapant :

http://www.newslang.ch/wp-json/wp/v2/posts?per_page=100

Vous choisissez d’afficher le 100 premiers articles de mon blog. Pour des raisons de clarté ce paramètre sera ignoré pour les futurs requêtes, gardez-le juste en tête.

Si on se concentre sur le résultat, il s’agit en fait d’un tableau (il commence et se termine par des crochets) contenant tous les articles et leur contenu. Voici la première partie du résultat retourné :

[  
   {  
      "id":380,
      "date":"2018-07-25T10:50:15",
      "date_gmt":"2018-07-25T08:50:15",
      "guid":{  
         "rendered":"https://newslang.ch/?p=380"
      },
      "modified":"2018-07-25T10:52:17",
      "modified_gmt":"2018-07-25T08:52:17",
      "slug":"comment-creer-un-shortcode-dans-wordpress",
      "status":"publish",
      "type":"post",
      "link":"https://newslang.ch/blog/comment-creer-un-shortcode-dans-wordpress/",
      "title":{  
         "rendered":"Comment cru00e9er un shortcode dans WordPress ?"
      },
      "content":{  
         "rendered":"[contenu de l'article]",
         "protected":false
      },
      "excerpt":{  
         "rendered":"[extrait de l'article]",
         "protected":false
      },
      "author":1,
      "featured_media":384,
      "comment_status":"closed",
      "ping_status":"closed",
      "sticky":false,
      "template":"",
      "format":"standard",

Il s’agit d’un extrait du contenu, mais on peut voir qu’il est possible d’accéder à toutes les informations de l’article : contenu, titre, id, date, auteur, image mise en avant, etc.

Filtrer le contenu retourné par l’API

Il est tout à fait possible d’affiner la recherche en donnant des filtres spécifiques, pour n’afficher par exemple que les articles appartenant à une catégorie spécifique. Imaginons que nous aimerions récupérer uniquement les articles appartenant à la catégorie comic sur mon blog. Il suffit d’ajouter un filtre comme suit :

http://www.newslang.ch/wp-json/wp/v2/posts?categories=14

Où l’on spécifie le filtre categories avec la valeur 14. Pourquoi 14 ? Il s’agit en fait de l’id unique de cette catégorie sur mon blog. On peut d’ailleurs récupérer cette information par l’API, mais il est nécessaire de connaitre le permalien de la catégorie. Pour afficher les articles de la catégorie comic sur mon blog il faut taper l’url suivante :

https://newslang.ch/category/blog/comic/

La partie en gras « comic » est en fait le permalien de ma catégorie comic. Ce permalien est appelé slug en anglais. Donc pour récupérer le détail de ma catégorie comic avec l’API on peut entrer :

http://www.newslang.ch/wp-json/wp/v2/categories?slug=comic

Et voici le résultat formaté de cette requête :

[
  {
    "id": 14,
    "count": 7,
    "description": "",
    "link": "https://newslang.ch/category/blog/comic/",
    "name": "Comic",
    "slug": "comic",
    "taxonomy": "category",
    "parent": 0,
    "meta": [],
    "_links": {
      "self": [
        {
          "href": "https://newslang.ch/wp-json/wp/v2/categories/14"
        }
      ],
      "collection": [
        {
          "href": "https://newslang.ch/wp-json/wp/v2/categories"
        }
      ],
      "about": [
        {
          "href": "https://newslang.ch/wp-json/wp/v2/taxonomies/category"
        }
      ],
      "wp:post_type": [
        {
          "href": "https://newslang.ch/wp-json/wp/v2/posts?categories=14"
        }
      ],
      "curies": [
        {
          "name": "wp",
          "href": "https://api.w.org/{rel}",
          "templated": true
        }
      ]
    }
  }
]

Et tout en haut vous pouvez voir "id":14 que j’ai utilisé précédemment pour filtrer les articles pour cette catégorie.

Cas pratique

Essayons de récupérer l’adresse de l’image mise en avant sur mon premier article, pour la catégorie comic. Pas très compliqué. Si on entre http://www.newslang.ch/wp-json/wp/v2/posts?categories=14, le premier résultat est le suivant :

[
    {
      "id": 367,
      "date": "2018-07-18T07:15:21",
      "date_gmt": "2018-07-18T05:15:21",
      "guid": {
        "rendered": "https://newslang.ch/blog/?p=367"
      },
      "modified": "2018-07-18T07:24:29",
      "modified_gmt": "2018-07-18T05:24:29",
      "slug": "comic-shop-en-ligne-securite-d-abord",
      "status": "publish",
      "type": "post",
      "link": "https://newslang.ch/blog/comic-shop-en-ligne-securite-d-abord/",
      "title": {
        "rendered": "Comic : Shop en ligne, la sécurité d'abord"
      },
      "content": {
        "rendered": "[contenu de l'article]",
        "protected": false
      },
      "author": 1,
      "featured_media": 782,
      "comment_status": "open",
      "ping_status": "open",
      "sticky": false,
      "template": "",
      "format": "standard",
      ...

Comme précédemment je n’en affiche qu’une partie. Vous pouvez voir, sur la ligne en évidence, la valeur featured_media. Il s’agit en fait de l’id unique de l’image mise en avant pour cet article. Alors à partir de là, rien de plus simple, on fait une requête à media pour récupérer le media avec l’id 782 :

https://www.newslang.ch/wp-json/wp/v2/media/782

Vous vous demandez peut-être pourquoi nous n’avons pas plutôt tapé https://www.newslang.ch/blog/wp-json/wp/v2/media?id=782, ce qui suivrait la logique expliquée jusqu’ici. La convention pour les API REST est que si on connait l’id du modèle (ici media) recherché, il suffit de renseigner son id à la suite pour retrouver l’élément.

On se retrouve avec le résultat suivant :

{
  "id": 782,
  "date": "2018-07-18T07:24:20",
  "date_gmt": "2018-07-18T05:24:20",
  ...
  "media_details": {
    "width": 740,
    "height": 501,
    "file": "2018/07/header-2.png",
    "sizes": {
      "thumbnail": {
        "file": "header-2-150x150.png",
        "width": 150,
        "height": 150,
        "mime_type": "image/png",
        "source_url": "https://newslang.ch/blog/wp-content/uploads/2018/07/header-2-150x150.png"
      },
      "medium": {
        "file": "header-2-300x203.png",
        "width": 300,
        "height": 203,
        "mime_type": "image/png",
        "source_url": "https://newslang.ch/blog/wp-content/uploads/2018/07/header-2-300x203.png"
      },
      ...

À nouveau j’ai raccourcis la réponse. Mais vous voyez que dans le contenu retourné, on dispose d’un attribut media_details dans lequel toutes les versions de l’image enregistrées (aperçus, vignettes, taille réel, etc.) sont accessibles, avec leurs tailles, leur type et leur adresse.

Conclusion

Je vous propose de jouer un peu avec cette API pour en découvrir plus et pour bien comprendre le fonctionnement d’une API REST. Si cette l’API de WordPress, publique par défaut, peut-être questionnable quant aux données mises à disposition à n’importe quel utilisateur (jusqu’à informer celui-ci des différentes révisions d’un article par exemple), elle n’en reste pas moins complète, puissante et facile à utiliser.

Dans le prochain article de la série, je vous montrerai comment contacter l’API et utiliser ses résultats retournés. Que ce soit en PHP, Javascript et, surtout, à l’intérieur d’un shortcode WordPress. D’ailleurs si ce n’est pas déjà fait, allez jeter un œil à mon article sur la création de shortcode dans WordPress !



0 commentaires

Soumettre un commentaire

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

derniers articles
de mon blog

Pin It on Pinterest