Guía completa para desarrolladores de la API REST de WordPress

La API REST de WordPress te permite trabajar con WordPress mediante solicitudes HTTP y JSON en lugar de las típicas pantallas de wp-admin. Con la API REST de WordPress, puedes obtener y actualizar contenido desde aplicaciones JavaScript, aplicaciones móviles, otros backends, o incluso scripts de automatización de una manera consistente.

En esta guía, aprenderás qué es la API REST de WP, cómo están estructurados los endpoints de la API REST de WordPress y cómo usarlos para construir integraciones reales y sitios headless.

En su núcleo, la API REST de WordPress expone los datos de tu sitio: publicaciones, páginas, usuarios, taxonomías y tipos de publicaciones personalizadas, a través de HTTP utilizando cargas útiles JSON. En lugar de renderizar una página HTML, WordPress puede responder a una solicitud con JSON estructurado que cualquier cliente puede interpretar, por lo que los endpoints de la API REST de WordPress son una pieza clave en arquitecturas headless y desacopladas.

WordPress viene con un conjunto de endpoints predeterminados de la API REST de WordPress bajo el espacio de nombres /wp-json/wp/v2/ que identifican cosas como enumerar publicaciones o crear nuevas. Cuando un cliente llama uno de estos endpoints, WordPress inicia su núcleo, dirige la solicitud a través de la infraestructura de la API REST de WP y devuelve JSON en lugar de HTML.

Por ejemplo, una simple solicitud GET a /wp-json/wp/v2/posts usa el enrutamiento integrado para devolver una lista de entradas, lo que funciona tanto si la haces desde una app en React, una app móvil nativa o un script del lado del servidor, usando después operaciones de posts para crear y actualizar contenido. Bajo el capó, se aplican las mismas comprobaciones de permisos, así que las llamadas autenticadas a la API de WordPress pueden ver borradores mientras que las llamadas anónimas solo ven contenido publicado.

La API se apoya en algunas ideas clave que verás en cada ejemplo de la API REST de WordPress.

• Las rutas son patrones de URL como /wp-json/wp/v2/posts, que se asignan a la lógica interna de WordPress.
• Los endpoints son la combinación de una ruta y un método HTTP, como GET /wp-json/wp/v2/posts o POST /wp-json/wp/v2/posts.
• JSON es el formato de datos utilizado para las solicitudes y respuestas, a veces descrito como la capa API JSON de WordPress porque estandariza cómo los clientes y servidores intercambian datos.

Una vez que comprendas esos conceptos básicos, la mayoría de los ejemplos de tutoriales de la API REST de WordPress se convertiran en un asunto de mapear operaciones CRUD a las rutas y métodos correctos.

Antes de empezar a hacer llamadas a los endpoints desde código, deberías confirmar que la API está habilitada, configurar la autenticación básica y preparar una forma de probar las solicitudes desde tu máquina.

Los requisitos más importantes son:

• Una instalación de WordPress razonablemente actualizada.
• Enlaces permanentes funcionales.
• Conciencia de lo que está expuesto públicamente en comparación con lo que está detrás de la autenticación.

En las instalaciones modernas de WordPress, el paso para habilitar la API REST es principalmente «verificar que funciona» en lugar de activar un interruptor. Visita /wp-json/ en tu navegador; si ves un índice JSON de espacios de nombres y rutas, la API REST está activa y lista.

Si la solicitud falla, verifica:

• Plugins de seguridad que bloquean el acceso a REST.
• Reglas personalizadas de .htaccess que niegan /wp-json/ o wp-json.php.
• Cortafuegos de nivel de hosting que bloquean estas rutas.

Una vez que se carga el índice base, puedes entrar en namespaces de rutas específicas o usar herramientas como Postman en lugar del navegador, lo cual es muy útil si estás probando un plugin de la REST API de WordPress desde un entorno local.

Para cualquier cosa más allá del contenido público, necesitarás autenticación de la API REST de WordPress. Las opciones más simples para pruebas locales son:

• Un plugin que habilita la autenticación básica o JWT, destinado solo para desarrollo o staging.
• Autenticación de cookies integrada cuando se prueba desde una sesión de navegador autenticada.

En producción, deberías evitar incluir credenciales directamente en los clientes y ser más cuidadoso con los métodos que utilizas, pero para experimentos iniciales, una capa de autenticación de la API JSON basada en plugins suele ser suficiente.

Una vez que la autenticación funciona, prueba los conceptos básicos con cURL para que no estés simplemente adivinando. Por ejemplo, para ejercer la API de WordPress para obtener publicaciones, podrías ejecutar:

curl https://example.com/wp-json/wp/v2/posts

Para llamar a un ejemplo de API REST de WordPress que requiere autenticación, puedes incluir encabezados o credenciales dependiendo del plugin y el método que hayas elegido. Esto también te permite probar un endpoint personalizado accediendo a su ruta antes de escribir cualquier código cliente, y comprobar que sigue funcionando si vuelves a habilitar o cambiar plugins.

Una vez que tu entorno esté listo, puedes comenzar a construir contra la API REST de WordPress de una manera estructurada. Los flujos típicos incluyen listar contenido, crear nuevos recursos, editarlos y eliminarlos, a menudo combinados con la paginación de la API REST de WordPress.

Para operaciones de lectura, se utilizan endpoints GET como GET /wp-json/wp/v2/posts o GET /wp-json/wp/v2/pages. Estas solicitudes GET respetan los permisos, de modo que los clientes públicos ven datos públicos, mientras que los clientes autenticados también pueden ver contenido privado o en borrador.

Puedes refinar las consultas GET de la API REST de WordPress con parámetros como ?per_page=10&page=2 o filtros por categorías y etiquetas, y las cabeceras te indican cuántas páginas hay disponibles, de modo que tu cliente puede construir interfaces de “cargar más” o scroll infinito sin tener que adivinar.

Para crear publicaciones u otros recursos, envía cargas útiles JSON al punto final relevante usando POST. Por ejemplo, una solicitud de publicación a /wp-json/wp/v2/posts con título, contenido y campos de estado te permite publicar o guardar contenido desde el código.

Debido a que estas operaciones cambian los datos, requieren autenticación de la API REST de WordPress y permisos adecuados, por lo que no debes exponerlas a clientes anónimos. En muchos casos, todavía combinarás esto con paginación cuando el cliente necesite obtener listas de elementos recién creados posteriormente.

La edición utiliza PUT o PATCH para enviar datos actualizados a un recurso existente. Una llamada típica a la API REST podría ser PUT /wp-json/wp/v2/posts/123 con un cuerpo JSON que contenga solo los campos que deseas cambiar.

Para eliminar publicaciones u otros recursos, usa DELETE en el endpoint apropiado. Por ejemplo, DELETE /wp-json/wp/v2/posts/123 le dice a la API REST de WordPress que mueva una publicación a la papelera o la elimine permanentemente según los argumentos que pases.

Como estas operaciones son destructivas, deberías considerar añadir protección adicional, como comprobaciones de roles y limitación de tasa (rate limiting) en herramientas orientadas a administración que las expongan en bloque.

Los endpoints predeterminados cubren los casos más comunes, pero a menudo necesitas lógica personalizada para reglas de negocio, flujos de datos externos o respuestas adaptadas. Ahí es donde entra el soporte de endpoints personalizados de la API REST de WordPress.

Considera agregar un endpoint personalizado de la API REST de WordPress cuando:

• Deseas exponer una parte específica de datos que no se mapea claramente a colecciones existentes.
• Necesitas realizar cálculos personalizados o combinar múltiples consultas antes de devolver JSON.
• Quieres una interfaz más limpia para los consumidores externos que las rutas de ejemplo predeterminadas de la API REST de WordPress.

Esto es especialmente común cuando construyes paneles de control, aplicaciones móviles o integraciones que no deberían tener que conocer los internos de WordPress.

Las rutas personalizadas se registran utilizando register_rest_route en un plugin o tema. Proporcionas un espacio de nombres, un patrón de ruta, métodos HTTP permitidos, y un callback, que crea un nuevo endpoint personalizado accesible bajo la ruta que elijas.

Por ejemplo, podrías registrar /wp-json/myplugin/v1/report para devolver estadísticas agregadas, utilizando endpoints existentes internamente pero presentándolos como una única respuesta optimizada para los clientes.

El callback que registras identifica la solicitud, ejecuta tu lógica y devuelve datos. Cuando escribes estas funciones, trátalas como cualquier otra API pública: valida las entradas, verifica permisos y protege contra el uso indebido.

Utiliza las comprobaciones de autenticación de la API REST de WordPress en tus callbacks de permisos y apóyate en funciones de seguridad como nonces, comprobaciones de capacidades (capability checks) y limitación de tasa (rate limiting) cuando sea apropiado. Los endpoints sensibles siempre deben verificar al usuario y pueden requerir un token nonce para reducir el riesgo de CSRF.

La autenticación determina quién puede hacer qué a través de la API y es central tanto para la seguridad como para la experiencia del usuario. Qué método de autenticación elijas depende de tu entorno, tipo de cliente y requisitos de seguridad.

La autenticación basada en cookies es lo que WordPress usa para usuarios autenticados en el área administrativa. Cuando un navegador está autenticado, la autenticación de la API REST de WordPress a través de cookies te permite llamar a endpoints desde JavaScript que se ejecuta en el mismo dominio sin encabezados adicionales.

Esto es conveniente para herramientas administrativas y paneles internos, pero no es adecuado para aplicaciones nativas de terceros o clientes entre dominios, que es donde entran otros métodos.

Para clientes externos y sistemas multitenencia, OAuth 2.0 es a menudo una mejor opción. Con un flujo OAuth, los usuarios otorgan acceso limitado a la API a través de tokens sin compartir contraseñas, alineándose con las mejores prácticas de seguridad más amplias.

Normalmente usarás un plugin o gateway que agrega soporte para OAuth sobre el núcleo, luego configuras alcances y tiempos de vida del token para que coincidan con los datos que tus clientes necesitan.

Las versiones modernas de WordPress también soportan contraseñas de aplicación, que son credenciales largas y aleatorias que se generan por usuario y por cliente. Estos funcionan bien para automatización entre servidores donde los inicios de sesión interactivos completos son excesivos.

Como las contraseñas de aplicación se integran con la autenticación y seguridad de la API REST de WordPress, suelen ser más fáciles de gestionar que crear tu propio sistema de tokens, especialmente para scripts de automatización pequeños y tareas de CI.

Una vez que domines lo básico, los patrones de ejemplo que usarás con más frecuencia se dividen en tres categorías: construcciones headless, integraciones y automatización.

En una configuración de WordPress headless, WordPress funciona como backend de contenido mientras que un frontend separado (React, Vue, Svelte o un generador de sitios estáticos) obtiene los datos a través de la API. Por eso las arquitecturas de WordPress como CMS headless se han vuelto populares: mantienen la experiencia editorial familiar, al mismo tiempo que ofrecen a los desarrolladores más libertad en el frontend.

Puedes alojar el cliente headless donde quieras y hacer que se comunique con la API a través de HTTPS; este desacoplamiento también facilita escalar el tráfico de lectura de forma independiente del área de administración.

La historia de integración de la API de WordPress es mucho más limpia con la REST API que con los antiguos XML-RPC o endpoints personalizados. Puedes hacer que los CRM, herramientas de marketing o sistemas internos creen y actualicen contenido a través de solicitudes autenticadas, o puedes reflejar datos de otros servicios en WordPress.

Al construir este tipo de integración, apóyate en patrones de ejemplo en la documentación y mantén un esquema claro para el JSON que envías y recibes para que ambos lados sigan siendo mantenibles con el tiempo.

WooCommerce expone sus propios endpoints, pero muchos equipos también utilizan la API principal para respaldar workflows. Por ejemplo, tu integración de la API de WordPress podría:

• Generar páginas de destino para nuevos productos automáticamente.
• Sincronizar datos de pedidos o clientes con herramientas externas.
• Activar un post para crear contenido cada vez que cambia un estado específico.

Debido a que el código de automatización tiende a tener una larga vida útil, querrás mantener la autenticación, las verificaciones de permisos y el manejo de errores ordenados desde el inicio.

Una vez que empieces a desplegar funcionalidades basadas en API, querrás establecer una serie de medidas de control en torno a la seguridad, la validación, el caché y el rendimiento. Estas prácticas de seguridad y confiabilidad ahorran mucho tiempo de depuración después.

Trata cada endpoint como una posible superficie de ataque. Usa las características de seguridad de la API REST de WordPress como:

• Verificaciones de capacidad (current_user_can) en las devoluciones de llamada de permisos.
• Nonces para operaciones sensibles, utilizando el mecanismo de nonce donde corresponda.
• HTTPS en todas partes, especialmente para llamadas autenticadas.

Si un endpoint no necesita ser público, restríngelo con autenticación en lugar de confiar en la «seguridad por oscuridad».

El manejo de entradas es tan importante como la autenticación. Siempre que aceptes datos, sanitiza y valida utilizando las funciones auxiliares de WordPress y esquemas estrictos. Esta es una parte esencial de la seguridad de la API REST de WordPress y ayuda a prevenir XSS, inyecciones SQL y otros problemas que pueden infiltrarse a través de las cargas JSON.

El almacenamiento en caché mantiene tu API receptiva bajo carga. Puedes almacenar en caché respuestas en varios niveles:

• En el cliente, utilizando encabezados HTTP estándar.
• En WordPress, almacenando resultados en transitorios o caché de objetos.
• En el edge, con una CDN delante de los endpoints públicos de la API REST de WordPress.

En sitios de alto tráfico, combinar el caché a nivel de WordPress con una infraestructura robusta (por ejemplo, ejecutando la aplicación en un VPS con suficiente CPU y RAM en lugar de hosting compartido sobrecargado) ayuda a que la API sirva respuestas de forma fiable incluso durante picos de tráfico.

Finalmente, observa los patrones de uso y agrega limitaciones de tasa donde tenga sentido. Medidas simples como rechazar clientes abusivos, paginar colecciones grandes y mover consultas pesadas fuera del camino crítico son muy efectivas.

Desde una perspectiva de infraestructura, colocar WordPress en un hosting de alto rendimiento, como un VPS de Contabo o un entorno similar con recursos dedicados, te da más margen para el tráfico de API que planes compartidos muy baratos. Eso, combinado con un diseño cuidadoso de endpoints, mantiene tu API REST de WordPress agradable para trabajar a medida que tu aplicación crece.