Guía de la API REST de WordPress

Qué es la API REST de WordPress

La API REST del ecosistema WordPress es una interfaz que permite a las aplicaciones externas comunicarse con un sitio WordPress mediante peticiones HTTP. En lugar de acceder al contenido a través del frontend o del panel de administración de WordPress, la API REST permite leer, crear, actualizar y eliminar contenido de forma programática, usando los métodos HTTP estándar (GET, POST, PUT, DELETE) y el formato JSON para el intercambio de datos.

La API REST está integrada en WordPress desde la versión 4.7 (diciembre de 2016) y representa la forma moderna de interactuar con WordPress. Se utiliza para aplicaciones móviles que muestran contenido de WordPress, frontends en JavaScript (React, Vue, Angular) que usan WordPress como backend, integraciones con servicios externos y la automatización de la gestión de contenidos. El editor Gutenberg, el editor estándar de WordPress desde la versión 5.0, usa intensivamente la API REST para todas las operaciones de contenido. Si estás empezando, consulta nuestra guía de instalación de WordPress.

Fundamentos de la API REST

Endpoints y rutas

La API REST de WordPress está disponible en tu sitio bajo la ruta /wp-json/. Con un navegador o una herramienta como cURL o Postman, puedes acceder a la API. Por ejemplo, una petición GET a /wp-json/wp/v2/posts devuelve una lista de entradas en formato JSON, /wp-json/wp/v2/pages devuelve páginas, /wp-json/wp/v2/categories devuelve categorías, /wp-json/wp/v2/users devuelve usuarios, /wp-json/wp/v2/media devuelve archivos multimedia y /wp-json/wp/v2/comments devuelve comentarios. Cada uno de estos endpoints admite distintos métodos HTTP para distintas operaciones: GET para leer, POST para crear, PUT/PATCH para actualizar y DELETE para eliminar.

Parámetros de consulta

La API REST admite numerosos parámetros para filtrar y paginar los resultados. El parámetro per_page controla el número de resultados por página (10 por defecto, máximo 100), page especifica la página de resultados para la paginación, search busca contenido por palabra clave, orderby define el campo de ordenación (date, title, id), order define la dirección de ordenación (asc o desc) y categories y tags filtran por categoría o etiqueta. Por ejemplo, la petición /wp-json/wp/v2/posts?per_page=5&categories=3&orderby=date&order=desc devuelve las 5 entradas más recientes de la categoría con ID 3.

Estructura de la respuesta

La API devuelve los datos en formato JSON. Cada objeto de entrada contiene id (identificador único), title con una propiedad rendered (título con formato HTML), content con una propiedad rendered (contenido de la entrada), excerpt con una propiedad rendered (extracto), date (fecha de publicación en formato ISO 8601), slug (título apto para URL), status (publish, draft, pending), author (ID del autor), categories y tags (arrays de IDs). Las cabeceras de respuesta HTTP contienen metadatos útiles: X-WP-Total (número total de elementos) y X-WP-TotalPages (número total de páginas).

Autenticación

Endpoints públicos vs protegidos

Algunos endpoints están disponibles públicamente sin autenticación: la lectura de entradas publicadas, páginas, categorías y etiquetas. Las operaciones que modifican datos (crear, actualizar, eliminar) y el acceso a datos privados requieren autenticación. La API REST de WordPress admite varios métodos de autenticación según el contexto de uso.

Application Passwords

Desde WordPress 5.6, las Application Passwords están integradas en el núcleo y representan la forma más sencilla de autenticar aplicaciones externas. Creas una Application Password para un usuario en Usuarios → Perfil → Application Passwords. La contraseña generada se usa con autenticación HTTP Basic: envías el nombre de usuario y la contraseña de aplicación en la cabecera Authorization de cada petición. Las Application Passwords tienen la ventaja de que se pueden revocar individualmente sin cambiar la contraseña principal del usuario.

Autenticación JWT

JSON Web Token (JWT) es un método de autenticación popular en aplicaciones de una sola página y aplicaciones móviles. WordPress no tiene soporte JWT integrado, pero plugins como JWT Authentication for WP REST API o Simple JWT Login añaden esta funcionalidad. El cliente envía el nombre de usuario y la contraseña al endpoint de token, obtiene un token JWT y luego lo envía en la cabecera Authorization como token Bearer en cada petición. Los tokens JWT tienen una vida limitada y se pueden renovar sin reenviar la contraseña.

OAuth 2.0

OAuth 2.0 es el estándar del sector para la autorización que permite a terceros acceder a recursos sin compartir contraseñas. WordPress admite OAuth a través del plugin OAuth Server. OAuth es ideal para aplicaciones que acceden al contenido de WordPress en nombre de un usuario: el usuario autoriza la aplicación a través de la página de inicio de sesión de WordPress, la aplicación recibe un token de acceso y lo usa para las llamadas a la API. Este es el método más seguro para aplicaciones en producción.

Crear endpoints personalizados

Registrar una ruta REST

WordPress permite crear endpoints de API personalizados para las necesidades específicas de tu aplicación. Usa la función register_rest_route() en el hook rest_api_init. Defines el namespace (p. ej., myplugin/v1), la ruta (p. ej., /featured-posts), el método HTTP (GET, POST), una función de callback que devuelve datos y una función opcional permission_callback para el control de acceso. Los endpoints personalizados son útiles para datos que requieren consultas complejas, agregaciones o transformaciones que los endpoints estándar no admiten.

Permission Callback

La función de permission callback controla quién puede acceder al endpoint. Para endpoints públicos, usa __return_true. Para endpoints protegidos, comprueba los permisos del usuario con la función current_user_can(). Por ejemplo, un endpoint para crear entradas debería comprobar current_user_can('publish_posts'). Nunca dejes los endpoints de escritura sin un permission callback, porque eso abre el sitio a abusos.

Validación y saneamiento de parámetros

Los endpoints personalizados deberían definir argumentos con validación y saneamiento. Para cada parámetro defines required (si es obligatorio), type (string, integer, boolean), validate_callback (función que comprueba la validez del valor) y sanitize_callback (función que limpia el valor antes de usarlo). WordPress ofrece funciones de saneamiento integradas como sanitize_text_field(), absint() y sanitize_email(). Una validación adecuada evita errores inesperados y vulnerabilidades de seguridad.

WordPress headless

El concepto de CMS headless

WordPress headless es una arquitectura en la que WordPress se utiliza únicamente como backend (CMS) para la gestión de contenidos, mientras que la presentación del frontend se ejecuta en una aplicación completamente independiente. La API REST de WordPress sirve de puente entre el backend y el frontend. El frontend puede construirse en React, Vue.js, Next.js, Nuxt, Angular o cualquier otro framework. Las ventajas son el control total del frontend, mejor rendimiento (páginas estáticas en lugar del renderizado PHP de WordPress), la posibilidad de usar el mismo contenido en un sitio web, una aplicación móvil y otras plataformas, y una experiencia de desarrollo moderna (hot reloading, arquitectura basada en componentes).

Next.js y WordPress

La combinación de Next.js y WordPress es una de las implementaciones headless más populares. Next.js ofrece renderizado del lado del servidor (SSR), generación de sitios estáticos (SSG) y regeneración estática incremental (ISR), lo que da lugar a sitios extremadamente rápidos. El contenido se obtiene de la API REST de WordPress durante la compilación (para SSG) o bajo demanda (para SSR). El componente Image de Next.js optimiza automáticamente las imágenes, y el sistema de enrutamiento mapea los slugs de WordPress a las páginas. Muchos sitios grandes usan esta combinación para las secciones de blog, mientras que el resto del sitio utiliza componentes personalizados.

Desafíos del headless

WordPress headless no está exento de desafíos. Pierdes los temas de WordPress y el personalizador visual: todo tiene que programarse en el framework del frontend. Los plugins que generan salida en el frontend (formularios de contacto, galerías, maquetadores de páginas) no funcionan en modo headless. La funcionalidad de previsualización requiere configuración adicional. Los plugins de SEO como Yoast generan metadatos, pero el frontend tiene que obtenerlos y mostrarlos correctamente. Los comentarios, la búsqueda y la paginación deben implementarse en el frontend mediante llamadas a la API. El enfoque headless requiere un equipo con experiencia en desarrollo frontend.

Seguridad de la API REST

Restringir el acceso

Por defecto, la API REST de WordPress está disponible públicamente y revela información sobre los usuarios, las entradas y la estructura del sitio. Para un sitio que no usa la API, considera restringir el acceso. Puedes deshabilitar la API REST para usuarios no autenticados mediante el filtro rest_authentication_errors, bloquear endpoints específicos (especialmente /wp/v2/users, que revela los nombres de usuario) o usar un plugin como Disable WP REST API para deshabilitarla de forma selectiva. Nunca bloquees la API REST por completo si usas el editor Gutenberg, porque depende de la API.

Limitación de peticiones (Rate Limiting)

Una API REST sin limitación de peticiones puede sufrir abusos para ataques de fuerza bruta, scraping de contenido o DDoS. Implementa la limitación de peticiones a nivel del servidor web (módulo limit_req de Nginx, mod_ratelimit de Apache) o mediante reglas WAF. El Rate Limiting de Cloudflare es una solución sencilla: limita el endpoint /wp-json/ a un número razonable de peticiones por minuto (p. ej., 60 para usuarios autenticados, 30 para no autenticados).

Herramientas útiles para trabajar con la API REST

• Postman: una herramienta gráfica para probar llamadas a la API con soporte para todos los métodos HTTP, autenticación y colecciones de peticiones.
• cURL: una herramienta de línea de comandos para peticiones HTTP, ideal para pruebas rápidas y scripting.
• Insomnia: una alternativa moderna a Postman con una interfaz limpia y soporte para GraphQL.
• WP-CLI: la herramienta de línea de comandos de WordPress que internamente usa la API REST y permite gestionar el sitio desde el terminal.
• Thunder Client: una extensión de VS Code para probar API directamente desde el editor.

Conclusión

La API REST de WordPress abre nuevas posibilidades para usar WordPress más allá del blog o el sitio tradicional. Tanto si estás construyendo una aplicación móvil, un frontend en JavaScript o integrando WordPress con otros sistemas, la API REST ofrece una forma estandarizada y documentada de acceder al contenido. Para proyectos headless, la combinación de WordPress y un framework de frontend moderno como Next.js ofrece lo mejor de ambos mundos: una gestión de contenidos sencilla y un rendimiento de primer nivel. En BeoHosting, todos los planes de hosting WordPress son compatibles con la API REST con configuraciones de PHP y MySQL optimizadas para respuestas más rápidas de la API.