L’API REST WordPress expliquée : routes, schéma et découvrabilité

Depuis la version 4.7, publiée fin 2016, WordPress embarque nativement une API REST complète. Ce n’est plus un plugin à installer ni une expérimentation : c’est une brique du cœur, disponible sur chaque installation par défaut. Pourtant, beaucoup de développeurs qui découvrent le headless en 2020 n’ont jamais pris le temps d’explorer sérieusement sa structure avant de s’y plonger tête baissée.

Cet article pose les bases : comment sont organisées les routes de l’API REST, comment lire le schéma d’un endpoint et comment tirer parti de la découvrabilité intégrée pour explorer ce que votre installation WordPress expose réellement. C’est le socle indispensable avant d’attaquer l’authentification ou la création d’endpoints personnalisés, sujets que nous aborderons dans de prochains articles.

Le point d’entrée : /wp-json/

Toute installation WordPress avec les permaliens activés expose son API à la racine /wp-json/. En visitant cette URL, vous obtenez un document JSON qui liste l’ensemble des routes disponibles, organisées par espace de noms (namespace). L’espace wp/v2 correspond aux routes natives du cœur : articles, pages, catégories, étiquettes, médias, utilisateurs, commentaires, etc.

Ce document racine n’est pas un détail cosmétique : c’est la porte d’entrée de la découvrabilité de l’API. Un client bien conçu peut, en théorie, découvrir dynamiquement les routes disponibles sans les coder en dur. Dans la pratique, on code presque toujours les routes en dur côté frontend, mais avoir ce document sous la main est précieux pour explorer une installation qu’on ne connaît pas encore.

Les routes principales de wp/v2

Voici les routes les plus utilisées au quotidien dans un projet headless :

• wp/v2/posts — les articles
• wp/v2/pages — les pages
• wp/v2/categories et wp/v2/tags — les taxonomies natives
• wp/v2/media — la bibliothèque de médias
• wp/v2/users — les utilisateurs (avec des champs limités si non authentifié)
• wp/v2/comments — les commentaires

Chaque route accepte une variante avec un identifiant : wp/v2/posts/42 renvoie l’article dont l’identifiant est 42. C’est du REST classique, sans surprise pour qui a déjà manipulé une API HTTP standard.

Lire le schéma d’un endpoint

Chaque route dispose d’un schéma OPTIONS consultable directement. En envoyant une requête OPTIONS vers /wp-json/wp/v2/posts, ou en ajoutant simplement ?context=edit à une requête authentifiée, vous obtenez la liste exhaustive des champs disponibles, leur type, leur description et s’ils sont modifiables. C’est un excellent réflexe avant d’intégrer un nouveau type de contenu dans un frontend : mieux vaut lire le schéma que deviner la structure en inspectant une seule réponse JSON.

Le paramètre context

Le paramètre context mérite une attention particulière, car il change réellement les champs renvoyés :

• view (par défaut) — les champs publics, adaptés à un affichage frontend
• embed — un sous-ensemble allégé, pensé pour les ressources incluses via _embed
• edit — l’ensemble des champs, y compris ceux réservés à l’administration, accessible uniquement avec les permissions adéquates

Un piège classique pour un débutant : chercher un champ comme raw sur le titre d’un article et ne pas comprendre pourquoi il n’apparaît pas en context=view. C’est normal : le contenu brut, non filtré par les hooks de rendu, n’est visible qu’en context=edit, réservé aux utilisateurs authentifiés disposant des droits d’édition.

Exposer vos propres types de contenu

Si votre projet utilise des types de contenu personnalisés (custom post types), rien n’est automatique : il faut explicitement demander leur exposition dans l’API REST via l’argument show_in_rest de register_post_type().

register_post_type( 'projet', array(
    'label'        => 'Projets',
    'public'       => true,
    'show_in_rest' => true,
    'rest_base'    => 'projets',
    'supports'     => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
) );

L’argument rest_base permet de choisir le nom de la route plutôt que de reprendre le slug du type de contenu par défaut. C’est utile quand le nom technique du post type ne correspond pas à ce que vous voulez exposer publiquement dans l’URL de l’API.

Il en va de même pour les taxonomies personnalisées : l’argument show_in_rest de register_taxonomy() doit être activé pour qu’elles apparaissent dans les réponses des articles associés et disposent de leur propre route.

Tester rapidement sans outil complexe

Pas besoin d’un client REST sophistiqué pour commencer à explorer : un navigateur suffit pour les requêtes GET publiques. Pour aller plus loin, la commande curl reste l’outil le plus rapide en ligne de commande.

curl -s "https://exemple.fr/wp-json/wp/v2/posts?per_page=2" | jq

Avant de coder le moindre appel depuis votre frontend, prenez cinq minutes pour explorer l’API à la main avec curl ou un navigateur. C’est le moyen le plus rapide de repérer une structure de données inattendue avant qu’elle ne casse votre composant React ou Vue en production.

En résumé

L’API REST de WordPress n’a rien d’obscur une fois qu’on comprend sa logique : un point d’entrée découvrable à /wp-json/, des routes organisées par espace de noms, un schéma consultable pour chaque endpoint, et un système de context qui adapte la réponse à l’usage prévu. Ces bases posées, vous êtes prêt à aborder les sujets plus concrets d’un projet headless : l’authentification pour les opérations d’écriture, la création d’endpoints personnalisés, et l’optimisation des requêtes pour éviter les appels en cascade. Ce sera l’objet des prochains articles de cette série.