La REST API de WordPress es una de esas piezas que puedes usar durante años sin pensar demasiado en ella. Abres el editor de bloques, guardas una entrada, una app externa consulta posts o un plugin pinta datos con JavaScript y todo parece normal. Pero por debajo hay una idea potente: WordPress no es solo una pantalla de administración y un tema PHP. También es una aplicación que expone datos, acciones y reglas de negocio mediante HTTP.
Entender la REST API empieza por consumirla y sigue por extenderla: abrir /wp-json/, probar endpoints core, consumir datos con fetch, registrar un endpoint propio, validar parámetros y definir un permission_callback real.
Qué resuelve la REST API
La REST API permite hablar con WordPress usando URLs, métodos HTTP y respuestas JSON. Eso la convierte en un contrato entre WordPress y otras capas: JavaScript en frontend, Gutenberg, una app headless, integraciones internas, dashboards, sistemas de migración o pequeñas herramientas de soporte.
Un endpoint como este devuelve posts en JSON:
/wp-json/wp/v2/postsY con parámetros puedes pedir una respuesta más concreta:
/wp-json/wp/v2/posts?per_page=5&_fields=id,title,link&search=wordpressEsto parece pequeño, pero en producción marca una diferencia enorme. No siempre necesitas cargar una plantilla completa, ni montar una consulta PHP en una página, ni pasar datos por variables globales. A veces necesitas una superficie clara para pedir solo lo que hace falta y renderizar una interfaz encima.
Primero, entender los endpoints core
Antes de registrar endpoints propios conviene explorar los que ya existen. Un buen punto de partida es abrir /wp-json/ y revisar /wp-json/wp/v2/posts, probando parámetros como _fields, per_page, search y status.
_fields es especialmente útil porque reduce el tamaño de la respuesta. Si solo necesitas ID, título y enlace, no tiene sentido traerte todo el objeto de un post con campos que no vas a usar. Esta mentalidad de pedir menos datos ayuda tanto a rendimiento como a claridad del código.
status introduce otra conversación importante: permisos. Un usuario anónimo puede leer contenido público, pero no debería poder listar borradores o datos internos. La REST API no va solo de endpoints bonitos; va de exponer la información correcta al usuario correcto.
Consumir datos con JavaScript moderno
El siguiente paso natural es consumir un endpoint desde JavaScript. Un ejemplo mínimo con fetch y async/await podría ser este:
async function loadPosts() {
const response = await fetch('/wp-json/wp/v2/posts?per_page=5&_fields=id,title,link');
if (!response.ok) {
throw new Error('No se pudieron cargar los posts');
}
return response.json();
}Lo importante no es solo que funcione en el happy path. Lo interesante es pensar como si eso fuese una interfaz real: estado de carga, estado vacío, error de red, respuesta inválida y renderizado estable. Una lista de posts consumida desde REST debería poder decir “cargando”, “no hay resultados” o “algo ha fallado” sin romper la experiencia.
Ese enfoque conecta WordPress con frontend moderno sin necesidad de convertir todo en una aplicación gigantesca. Puedes usarlo para un bloque interactivo, un buscador, un panel privado o una herramienta interna dentro de un proyecto clásico.
Cuándo tiene sentido un endpoint custom
Los endpoints core cubren muchísimo, pero hay casos donde no quieres exponer la estructura cruda de WordPress. Quieres una respuesta pensada para un caso de uso concreto: un resumen, un informe, un cálculo, datos ya normalizados o una acción que combine varias fuentes.
Ahí entra register_rest_route(). Por ejemplo, para exponer un resumen en /wp-json/my-plugin/v1/stats, una forma simplificada sería:
add_action('rest_api_init', function () {
register_rest_route('my-plugin/v1', '/stats', [
'methods' => 'GET',
'callback' => 'my_plugin_get_stats',
'permission_callback' => '__return_true',
]);
});Si el endpoint es público y solo devuelve información pública, __return_true puede tener sentido. Pero en cuanto el endpoint expone datos internos, dispara acciones o depende de información privada, esa decisión deja de ser aceptable.
La parte que separa demo de producción
Un endpoint defendible necesita validación, sanitización y permisos. No basta con que devuelva JSON. Tiene que responder bien cuando falta un parámetro, cuando el parámetro tiene un formato incorrecto y cuando el usuario no tiene permiso.
add_action('rest_api_init', function () {
register_rest_route('my-plugin/v1', '/stats', [
'methods' => 'GET',
'callback' => 'my_plugin_get_private_stats',
'permission_callback' => function () {
return current_user_can('edit_posts');
},
'args' => [
'post_id' => [
'required' => true,
'sanitize_callback' => 'absint',
'validate_callback' => function ($value) {
return absint($value) > 0;
},
],
],
]);
});Este detalle cambia mucho la lectura profesional del código. absint deja claro que esperas un entero positivo. sanitize_text_field encaja cuando recibes texto simple. current_user_can() expresa una regla de negocio real. Y una respuesta de error controlada permite depurar sin convertir la API en una caja negra.
Por qué importa para Gutenberg y para headless
La REST API es importante porque WordPress moderno ya no vive solo en el ciclo clásico de plantilla PHP. El editor de bloques, muchas pantallas del administrador y cada vez más interfaces personalizadas dependen de intercambiar datos de forma estructurada.
Si entiendes la REST API, entiendes mejor cómo se comunican Gutenberg, plugins, bloques dinámicos, aplicaciones headless y herramientas internas. Puedes decidir cuándo conviene renderizar en PHP, cuándo conviene hidratar una pieza con JavaScript y cuándo merece la pena diseñar un endpoint propio.
También te obliga a pensar en contratos. Qué datos expongo. Qué forma tienen. Qué permisos los protegen. Qué errores pueden aparecer. Qué ocurre si mañana otro equipo consume el endpoint. Esa mentalidad es muy distinta a “hago una query y pinto HTML”.
Checklist mental para un endpoint
- ¿El endpoint debe ser público o autenticado?
- ¿Qué capability concreta protege la acción?
- ¿Qué parámetros acepta y cómo se validan?
- ¿La respuesta devuelve solo los campos necesarios?
- ¿Hay estados de error claros y predecibles?
- ¿La interfaz que lo consume contempla loading, error y empty?
- ¿El endpoint está documentado con ejemplos reales?
Cierre
La REST API no es solo una puerta para hacer WordPress headless. Es una forma de pensar WordPress como plataforma. Te permite separar datos de presentación, crear integraciones limpias, construir interfaces más ricas y definir contratos técnicos que otros desarrolladores pueden entender.
En proyectos reales, esa base aparece una y otra vez: endpoints core, JavaScript real, seguridad mínima y endpoints propios bien definidos. No es teoría abstracta. Es el tipo de trabajo que convierte WordPress de “una web” en una pieza central de producto.