La REST API de WordPress: qué es y cómo usarla

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:

Cada endpoint de colección admite parámetros de consulta muy útiles: ?per_page=5 limita resultados, ?search=wordpress busca, ?categories=12 filtra por categoría, ?orderby=date&order=asc ordena y ?_fields=id,title,link devuelve solo los campos que pidas, aligerando la respuesta. Para un elemento concreto se añade su ID: /wp-json/wp/v2/posts/123.

Las respuestas JSON de WordPress llegan sin formato, en una sola línea difícil de leer. Un truco de flujo de trabajo: pega la respuesta en nuestro formateador y validador JSON gratuito y tendrás el árbol indentado y coloreado para inspeccionarlo con comodidad.

Paginación: las cabeceras que debes conocer

Los endpoints de colección devuelven como máximo 100 elementos por petición (10 por defecto). Para recorrer catálogos grandes, la API incluye en cada respuesta dos cabeceras HTTP: X-WP-Total, con el número total de elementos, y X-WP-TotalPages, con el número de páginas disponible según tu per_page. Basta con iterar añadiendo ?page=2, ?page=3 y así sucesivamente hasta alcanzar la última. Si pides una página inexistente, la API responde con un error 400 con el código rest_post_invalid_page_number, una señal cómoda para detener el bucle en scripts de exportación o migración.

Autenticación con Application Passwords

Leer contenido público no requiere identificarse, pero crear, editar o borrar sí. Desde WordPress 5.6 el método integrado y recomendado son las Application Passwords (contraseñas de aplicación): claves específicas por aplicación, revocables individualmente y que no exponen tu contraseña real.

Para crear una: entra en Usuarios → Perfil, baja hasta «Contraseñas de aplicación», escribe un nombre descriptivo (por ejemplo «Script de publicación») y pulsa crear. WordPress te mostrará una sola vez una clave con el formato xxxx xxxx xxxx xxxx xxxx xxxx. Guárdala en un gestor de contraseñas o en un fichero de variables de entorno, nunca en el código fuente.

La clave se usa con autenticación HTTP Basic: usuario y contraseña de aplicación codificados en Base64 en la cabecera Authorization. Requisito imprescindible: la web debe servirse por HTTPS, porque en HTTP plano las credenciales viajarían expuestas.

Prueba rápida desde la terminal con 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 respuesta es un JSON con el ID del nuevo borrador, la autenticación funciona. Cada permiso depende del rol del usuario: una contraseña de aplicación de un suscriptor no podrá publicar entradas.

Leer y crear contenido: ejemplos con JavaScript

Veamos la API en acción con fetch, tal y como lo harías en una web externa o una aplicación. Primero, leer los últimos artículos de un blog (sin autenticación, contenido público):

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();

Y ahora, crear una entrada autenticándonos con una Application Password (esto debe ejecutarse en un entorno servidor o script privado, nunca en el navegador de tus visitantes, porque expondría la clave):

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();

Fíjate en el detalle de title.rendered al leer: la API devuelve los campos de texto como objetos con las variantes rendered (HTML final) y, si estás autenticado con permisos de edición y añades ?context=edit, también raw (contenido original).

Crear tus propios endpoints con register_rest_route

La API del núcleo cubre el contenido estándar, pero el verdadero potencial llega cuando expones datos propios. Con register_rest_route() puedes crear rutas personalizadas bajo tu propio espacio de nombres. Ejemplo completo: un endpoint que devuelve estadísticas básicas del sitio, con un parámetro validado y control de permisos:

<?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' ),
    ) );
}

Tras guardar este código (en un plugin o snippet), tu nuevo endpoint responde en https://tudominio.com/wp-json/biblioweb/v1/estadisticas?tipo=page. Tres reglas de oro: usa siempre un espacio de nombres propio con versión (biblioweb/v1), define permission_callback explícitamente (es obligatorio desde WordPress 5.5; para endpoints privados usa una comprobación como current_user_can( 'edit_posts' )) y valida cada parámetro de entrada. La referencia completa está en el manual oficial de la REST API de WordPress.

Seguridad: qué exponer y qué proteger

La REST API de WordPress es segura por diseño (solo expone lo que ya es público y exige permisos para escribir), pero conviene ajustar algunos detalles:

• Enumeración de usuarios: el endpoint /wp/v2/users lista autores con contenido publicado, lo que facilita a un atacante conocer nombres de usuario válidos. Muchos plugins de seguridad lo restringen; también puede filtrarse por código para requerir autenticación.
• HTTPS obligatorio: sin certificado SSL, las Application Passwords viajan en claro. No hay excepción razonable a esta regla.
• Principio de mínimo privilegio: crea las contraseñas de aplicación con un usuario cuyo rol tenga solo los permisos que la integración necesita, y revócalas cuando dejen de usarse.
• No desactives la API a lo bruto: el editor de bloques y muchos plugins dependen de ella. Si quieres limitarla, exige autenticación con el filtro rest_authentication_errors en lugar de bloquearla por completo.
• Limita la superficie: los endpoints personalizados públicos deben devolver solo datos que no te importe que sean visibles para cualquiera.

Estas precauciones encajan dentro de una estrategia general de endurecimiento; si quieres repasarla, tenemos una guía con trucos para reforzar la seguridad de tu WordPress.

Preguntas frecuentes

¿La REST API de WordPress está activa en mi web?

Casi con total seguridad, sí: viene activada de serie desde WordPress 4.7 (2016). Compruébalo visitando tudominio.com/wp-json/: si ves un JSON con el nombre de tu sitio y el listado de rutas, está operativa. Si devuelve un 404, revisa los enlaces permanentes o algún plugin de seguridad que la esté bloqueando.

¿Es peligroso tener la API activada?

No más que tener la web publicada. La API de lectura solo expone contenido que ya es público en tu web, y toda operación de escritura exige autenticación y permisos. Los dos ajustes sensatos son restringir el listado de usuarios y asegurarte de servir todo por HTTPS. Desactivarla por completo suele causar más problemas de los que evita.

¿Puedo usar la API con custom post types y campos personalizados?

Sí. Los custom post types aparecen en la API si se registraron con show_in_rest => true, y obtienen su propio endpoint (por ejemplo /wp/v2/proyecto). Los campos personalizados se exponen con register_post_meta() marcando también show_in_rest, o con el campo meta de la propia entrada si el plugin que los crea lo soporta.

¿Qué diferencia hay entre la REST API y WPGraphQL?

La REST API es el estándar del núcleo: cada tipo de dato tiene su endpoint y las respuestas tienen estructura fija. GraphQL (vía el plugin WPGraphQL) permite pedir exactamente los campos que necesitas en una sola consulta, lo que gusta en proyectos headless complejos. Para automatizaciones, integraciones y la mayoría de proyectos, la REST API es más simple, no requiere plugins y está soportada oficialmente.

Conclusión

La REST API de WordPress convierte tu web en una plataforma programable: un índice claro de endpoints bajo /wp-json/wp/v2/, autenticación integrada con Application Passwords sobre HTTPS y la posibilidad de ampliar el mapa con rutas propias mediante register_rest_route(). Con lo visto en esta guía puedes leer contenido público desde cualquier aplicación, publicar y editar mediante scripts autenticados, exponer datos a medida con validación y permisos, y hacerlo con las precauciones de seguridad adecuadas. El mejor camino para interiorizarla es práctico: abre tudominio.com/wp-json/wp/v2/posts?per_page=3 en el navegador, pasa la respuesta por un formateador JSON para entender su estructura, crea tu primera Application Password y lanza un borrador desde curl. En quince minutos habrás cruzado la puerta que separa usar WordPress de programar con WordPress.