L'API REST de WordPress : ce que c'est et comment l'utiliser

Tu WordPress no es solo una web: también es un servidor de datos. Desde la versión 4.7, la REST API de WordPress viene integrada en el núcleo y expone entradas, páginas, usuarios, medios y taxonomías en formato JSON, listos para ser leídos o modificados desde cualquier aplicación externa: una app móvil, un script de automatización, otra web o un panel de control a medida. Es la tecnología que hace funcionar el editor de bloques, la que usan miles de integraciones y la puerta de entrada al llamado WordPress «headless». Y, sin embargo, muchos usuarios avanzados no la han explorado nunca. En esta guía práctica veremos qué es exactamente la REST API de WordPress, cómo están organizados sus endpoints, cómo autenticarte de forma segura con Application Passwords, cómo leer y crear contenido con ejemplos reales (desde el navegador, con JavaScript y con PHP), cómo crear tus propios endpoints y qué precauciones de seguridad conviene tomar. Todo con código funcional que puedes probar hoy en tu propia web.

Qué es la REST API de WordPress y para qué sirve

Una API REST es una interfaz que permite a dos sistemas comunicarse sobre HTTP usando las operaciones clásicas del protocolo: GET para leer, POST para crear, PUT/PATCH para actualizar y DELETE para borrar. La respuesta llega en JSON, un formato de texto ligero que cualquier lenguaje entiende. En el caso de WordPress, eso significa que todo lo que gestionas desde el escritorio (entradas, páginas, comentarios, categorías, usuarios, medios) tiene también una «puerta trasera» estructurada y oficial para máquinas.

Casos de uso reales donde la REST API de WordPress marca la diferencia:

• Automatización: publicar o actualizar contenido desde scripts, hojas de cálculo o herramientas como n8n y Make.
• Headless WordPress: usar WordPress solo como gestor de contenido y montar el frontend con React, Vue o Astro.
• Apps móviles: la app oficial de WordPress funciona íntegramente sobre esta API.
• Integraciones entre webs: mostrar en una web los últimos artículos de otra, sincronizar catálogos, centralizar publicación.
• Paneles a medida: dashboards que leen y escriben en WordPress sin pasar por wp-admin.

La API es también la base de integraciones modernas con inteligencia artificial: plugins como AI Engine, que convierte tu WordPress en un agente de IA, se apoyan en ella para exponer el contenido a asistentes externos.

Endpoints principales: el mapa de la API

Todo empieza en una URL: https://tudominio.com/wp-json/. Ábrela en el navegador y verás el índice completo de rutas disponibles. Los endpoints del núcleo cuelgan del espacio de nombres wp/v2:

Chaque point d'accès de collection accepte des paramètres de requête très utiles : ?per_page=5 limite les résultats, ?search=wordpress recherche, ?categories=12 filtre par catégorie, ?orderby=date&order=asc trie et ?_fields=id,title,link renvoie uniquement les champs que vous demandez, allégeant la réponse. Pour un élément concret, son ID est ajouté : /wp-json/wp/v2/posts/123.

Les réponses JSON de WordPress arrivent sans formatage, sur une seule ligne difficile à lire. Une astuce de flux de travail : collez la réponse dans notre formateur et validateur JSON gratuit et vous aurez l'arbre indenté et coloré pour l'inspecter confortablement.

Pagination : les en-têtes que vous devez connaître

Les points d'accès de collection renvoient au maximum 100 éléments par requête (10 par défaut). Pour parcourir de grands catalogues, l'API inclut dans chaque réponse deux en-têtes HTTP : X-WP-Total, avec le nombre total d'éléments, et X-WP-TotalPages, avec le nombre de pages disponible selon votre per_page. Il suffit d'itérer en ajoutant ?page=2, ?page=3 et ainsi de suite jusqu'à atteindre la dernière. Si vous demandez une page inexistante, l'API répond avec une erreur 400 avec le code rest_post_invalid_page_number, un signal pratique pour arrêter la boucle dans les scripts d'exportation ou de migration.

Authentification avec les mots de passe d'application

Lire du contenu public ne nécessite pas d'identification, mais créer, modifier ou supprimer oui. Depuis WordPress 5.6, la méthode intégrée et recommandée est celle des Mots de passe d'application (mots de passe d'application) : clés spécifiques par application, révocables individuellement et qui n'exposent pas votre mot de passe réel.

Pour en créer une : allez dans Utilisateurs → Profil, descendez jusqu'à « Mots de passe d'application », saisissez un nom descriptif (par exemple « Script de publication ») et cliquez sur créer. WordPress vous affichera une seule fois une clé au format xxxx xxxx xxxx xxxx xxxx xxxx. Enregistrez-la dans un gestionnaire de mots de passe ou dans un fichier de variables d'environnement, jamais dans le code source.

La clé est utilisée avec l'authentification HTTP Basic : nom d'utilisateur et mot de passe d'application encodés en Base64 dans l'en-tête Authorization. Exigence essentielle : le site web doit être servi via HTTPS, car en HTTP simple, les identifiants seraient exposés.

Test rapide depuis le terminal avec curl :

curl -X POST https://tudominio.com/wp-json/wp/v2/posts \
  -u "tu_usuario:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Borrador desde la API","status":"draft"}'

Si la réponse est un JSON avec l'ID du nouveau brouillon, l'authentification fonctionne. Chaque permission dépend du rôle de l'utilisateur : un mot de passe d'application d'un abonné ne pourra pas publier d'articles.

Lire et créer du contenu : exemples avec JavaScript

Voyons l'API en action avec fetch, comme vous le feriez sur un site web externe ou une application. Tout d'abord, lire les derniers articles d'un blog (sans authentification, contenu public) :

const API = 'https://tudominio.com/wp-json/wp/v2';

async function ultimasEntradas() {
  const res = await fetch(`${API}/posts?per_page=5&_fields=id,title,link,date`);
  if (!res.ok) {
    throw new Error('Error HTTP ' + res.status);
  }
  const posts = await res.json();
  posts.forEach((post) => {
    console.log(`${post.date} — ${post.title.rendered} — ${post.link}`);
  });
}

ultimasEntradas();

Et maintenant, créer une entrée en nous authentifiant avec un mot de passe d'application (cela doit être exécuté dans un environnement serveur ou un script privé, jamais dans le navigateur de vos visiteurs, car cela exposerait la clé) :

const usuario = 'tu_usuario';
const clave   = 'xxxx xxxx xxxx xxxx xxxx xxxx';
const token   = Buffer.from(`${usuario}:${clave}`).toString('base64');

async function crearEntrada() {
  const res = await fetch('https://tudominio.com/wp-json/wp/v2/posts', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Publicado por la REST API',
      content: '<p>Este contenido lo ha creado un script.</p>',
      status: 'draft',
      categories: [12],
    }),
  });
  const data = await res.json();
  if (!res.ok) {
    throw new Error(data.message || 'Error al crear la entrada');
  }
  console.log('Creada con ID', data.id, '→', data.link);
}

crearEntrada();

Notez le détail de title.rendered lors de la lecture : l'API renvoie les champs de texte sous forme d'objets avec les variantes rendered (HTML final) et, si vous êtes authentifié avec des permissions d'édition et que vous ajoutez ?context=edit, aussi raw (contenu original).

Créer vos propres points d'accès avec register_rest_route

L'API du cœur couvre le contenu standard, mais le véritable potentiel apparaît lorsque vous exposez vos propres données. Avec register_rest_route() vous pouvez créer des routes personnalisées sous votre propre espace de noms. Exemple complet : un point d'accès qui renvoie des statistiques de base du site, avec un paramètre validé et un contrôle des permissions :

<?php
add_action( 'rest_api_init', function () {
    register_rest_route( 'biblioweb/v1', '/estadisticas', array(
        'methods'             => 'GET',
        'callback'            => 'biblioweb_api_estadisticas',
        'permission_callback' => '__return_true', // Endpoint público de solo lectura.
        'args'                => array(
            'tipo' => array(
                'default'           => 'post',
                'sanitize_callback' => 'sanitize_key',
                'validate_callback' => function ( $valor ) {
                    return post_type_exists( $valor );
                },
            ),
        ),
    ) );
} );

function biblioweb_api_estadisticas( WP_REST_Request $request ) {
    $tipo     = $request->get_param( 'tipo' );
    $conteo   = wp_count_posts( $tipo );
    $usuarios = count_users();

    return rest_ensure_response( array(
        'tipo'        => $tipo,
        'publicados'  => (int) $conteo->publish,
        'borradores'  => (int) $conteo->draft,
        'usuarios'    => (int) $usuarios['total_users'],
        'generado_en' => current_time( 'mysql' ),
    ) );
}

Après avoir enregistré ce code (dans un plugin ou un snippet), votre nouveau point d'accès répond à https://tudominio.com/wp-json/biblioweb/v1/estadisticas?tipo=page. Trois règles d'or : utilisez toujours un espace de noms propre avec version (biblioweb/v1), définissez permission_callback explicitement (c'est obligatoire depuis WordPress 5.5 ; pour les points d'accès privés, utilisez une vérification comme current_user_can( 'edit_posts' )) et valide chaque paramètre d'entrée. La référence complète se trouve dans le manuel officiel de l'API REST de WordPress.

Sécurité : quoi exposer et quoi protéger

L'API REST de WordPress est sécur

• Énumération des utilisateurs : l'endpoint /wp/v2/users liste les auteurs avec du contenu publié, ce qui facilite à un attaquant de connaître des noms d'utilisateur valides. De nombreux plugins de sécurité le restreignent ; il peut aussi être filtré par code pour exiger une authentification.
• HTTPS obligatoire : sans certificat SSL, les mots de passe d'application voyagent en clair. Il n'y a pas d'exception raisonnable à cette règle.
• Principe du moindre privilège : créez les mots de passe d'application avec un utilisateur dont le rôle n'a que les permissions nécessaires à l'intégration, et révoquez-les lorsqu'elles ne sont plus utilisées.
• Ne désactivez pas l'API brutalement : l'éditeur de blocs et de nombreux plugins en dépendent. Si vous voulez la limiter, exigez une authentification avec le filtre rest_authentication_errors au lieu de la bloquer complètement.
• Limitez la surface : les endpoints personnalisés publics ne doivent renvoyer que des données que vous ne craignez pas de rendre visibles à quiconque.

Ces précautions s'inscrivent dans une stratégie générale de durcissement ; si vous voulez la revoir, nous avons un guide avec astuces pour renforcer la sécurité de votre WordPress.

Questions fréquentes

L'API REST de WordPress est-elle active sur mon site web ?

Presque certainement, oui : elle est activée par défaut depuis WordPress 4.7 (2016). Vérifiez-le en visitant tudominio.com/wp-json/: si vous voyez un JSON avec le nom de votre site et la liste des routes, elle est opérationnelle. Si elle renvoie un 404, vérifiez les permaliens ou un plugin de sécurité qui la bloque.

Est-il dangereux d'avoir l'API activée ?

Pas plus que d'avoir le site web publié. L'API de lecture n'expose que le contenu déjà public sur votre site web, et toute opération d'écriture exige une authentification et des permissions. Les deux réglages sensés sont de restreindre la liste des utilisateurs et de s'assurer de tout servir via HTTPS. La désactiver complètement cause généralement plus de problèmes qu'elle n'en évite.

Puis-je utiliser l'API avec les types de publication personnalisés et les champs personnalisés ?

Oui. Les types de publication personnalisés apparaissent dans l'API s'ils ont été enregistrés avec show_in_rest => true, et obtiennent leur propre endpoint (par exemple /wp/v2/proyecto). Les champs personnalisés sont exposés avec register_post_meta() en cochant également show_in_rest, ou avec le champ meta de l'entrée elle-même si le plugin qui les crée le supporte.

Quelle est la différence entre l'API REST et WPGraphQL ?

L'API REST est le standard du noyau : chaque type de donnée a son endpoint et les réponses ont une structure fixe. GraphQL (via le plugin WPGraphQL) permet de demander exactement les champs dont vous avez besoin en une seule requête, ce qui est apprécié dans les projets headless complexes. Pour les automatisations, les intégrations et la plupart des projets, l'API REST est plus simple, ne nécessite pas de plugins et est officiellement supportée.

Conclusion

L'API REST de WordPress transforme votre site web en une plateforme programmable : un index clair d'endpoints sous /wp-json/wp/v2/, authentification intégrée avec les mots de passe d'application sur HTTPS et la possibilité d'étendre la carte avec vos propres routes via register_rest_route(). Avec ce qui est présenté dans ce guide, vous pouvez lire du contenu public depuis n'importe quelle application, publier et éditer via des scripts authentifiés, exposer des données personnalisées avec validation et permissions, et le faire avec les précautions de sécurité appropriées. La meilleure façon de l'assimiler est pratique : ouvrez tudominio.com/wp-json/wp/v2/posts?per_page=3 dans le navigateur, passez la réponse par un formateur JSON pour comprendre sa structure, créez votre premier mot de passe d'application et lancez un brouillon depuis curl. En quinze minutes, vous aurez franchi la porte qui sépare l'utilisation de WordPress de la programmation avec WordPress.