WordPress es una herramienta muy versátil gracias a su ecosistema, utilizando este CMS podemos crear todo tipo de páginas web, blogs, tiendas y casi cualquier cosa que se nos ocurra. ¿Pero qué sucede si quieremos integrar el CMS con otro proyecto y no nos basta con los plugins existentes? ¿Y si lo que queremos es extender las funcionalidades que nos brinda? Históricamente se han desarrollado plugins o integrado aplicaciones accediendo a la base de datos de WordPress pero actualmente gozamos de una alternativa mucho mejor, más desacoplada y sencilla de utilizar que sin duda es una de las grandes mejoras en los últimos tiempos en el mundo WordPress, la inclusión de una API REST que nos ofrece endpoints para tratar con la información que alberga el sistema.

¿Qué es una API REST?

REST es el acrónimo de Representational State Transfer, se trata de un conjunto de principios de arquitectura para la comunicación de información. Por tanto una API REST (o RESTful) es cualquiera que cumpla los principios que se definen. Normalmente el término se suele utilizar de manera amplia para definir cualquier webservice que no mantenga estado (stateless), que utilice HTTP y sus verbos para la comunicación y que disponga de cierta estructura para las URIs que referencian de manera única a cada entidad.

Los principios que se deben cumplir para que una API sea considerada RESTful van todos enfocados a mejorar el rendimiento, escalabilidad, simplicidad y en general el sistema. A continuación los resumimos brevemente:

• Arquitectura Cliente-Servidor: Este punto está enfocado a optimizar los recursos separando claramente las responsabilidades y optimizando cada parte para su finalidad.
• Carencia de estado: La API debe ser stateless, para ello no debe existir ninguna información que se comparta entre peticiones a modo de contexto. No se establecerá un contexto en el servidor que perdure la primera vez que cliente y servidor se comuniquen sino que cada petición será independiente del resto que se realicen.
• Posibilidad de uso de caché: Se debe tener en cuenta el uso de caché y definir las respuestas como cacheables o no de manera que el cliente no tengan información errónea y a la vez se pueda minimizar el número de peticiones a realizar.
• Arquitectura por capas: El cliente no debe ser capaz de diferenciar una respuesta servida directamente por el servidor o por un intermediario de modo que por ejemplo se podrán utilizar balanceadores de carga para permitir al servicio escalar.
• Scripting en el cliente: Se menciona como punto opcional el hecho de que el servidor tenga la capacidad de enviar scripts al cliente para poder extender su funcionalidad.
• Interfaz uniforme: Es una parte fundamental de REST y define varios puntos.
  • Un recurso debe ser identificable por una petición, es decir la URI del recurso lo identifica y es independiente de la representación del mismo que el servidor nos entregue en la respuesta (que podría ser xml o json como el caso de la API de WordPress).
  • Cuando el cliente obtiene la representación del recurso ésta contiene suficiente información como para poder modificarlo o borrarlo.
  • Cada mensaje tiene suficiente información para describir cómo debe ser manipulado.
  • HATEOAS (Hypermedia as the engine of application state): Tras recibir la representación de un elemento el cliente debe poder descubrir las acciones disponibles y los recursos necesarios a partir de enlaces que el propio servidor proveerá.

Una vez claros los fundamentos vamos a ver de manera muy sencilla cómo podemos utilizar la API que nos ofrece WordPress. Para los ejemplos de este artículo vamos a crear pequeñas aplicaciones en PHP o lanzar peticiones con la herramienta HTTPie por lo que es recomendable tener al menos uno instalado aunque las peticiones se pueden lanzar desde cualquier aplicación que nos lo permita, como curl, Postman, cualquier lenguaje de programación que nos permita hacer peticiones HTTP o nuestro navegador web.

Primeros pasos con la API

Podemos empezar a utilizar la API REST de WordPress simplemente lanzando peticiones HTTP a los endpoints disponibles en /wp-json/wp/v2/ que nos responderán con un objeto JSON. Para algunas opciones eso será suficiente pero en otras necesitaremos autenticarnos. Para empezar podemos lanzar en nuestro terminal el comando http http://localhost/wp-json/wp/v2/posts y veremos como la respuesta contiene el listado de posts de nuestro WordPress.

Empezar a hacer algo útil con la API es tan sencillo como utilizar la respuesta que nos da el servidor, podríamos por ejemplo parsear y listar todos los posts con el título, la fecha y el enlace a la web.

Como hemos mencionado anteriormente para utilizar según qué endpoints es necesario autenticarse. Por defecto se incluye la autenticación con cookies, con este tipo de autenticación una vez hagamos login podremos utilizar la APIdesde la propia página. Este tipo de autenticación es muy útil para desarrollar plugins y temas que desean trabajar con la API.

En nuestras pruebas vamos a simular un sistema algo más complejo, imaginemos que tenemos una aplicación completamente independiente desde la que queremos gestionar nuestra instancia de WordPress, existe un plugin enfocado al desarrollo con la API que nos permite utiliza basic auth, únicamente tendremos que enviar en las peticiones nuestro usuario y contraseña. Es por eso que está enfocado al desarrollo ya que es inseguro, pero existen alternativas como plugins para autenticar con Oauth o JWT que son sistemas listos para producción.

Con el plugin instalado vamos a crear nuestra primera aplicación usando php para comunicarnos con la API usando la autenticación y comprobar que todo funciona correctamente. Para ello vamos a utilizar composer y requeriremos los paquetes guzzlehttp/guzzle y symfony/console. Existe una manera muy sencilla de crear comandos en un único fichero utilizando el componente symfony/console de manera que tendremos todas las ventajas que nos ofrece el paquete sin tener que crear todo un proyecto o utilizar el framework completo. Para la comunicación con la API utilizaremos guzzle que nos simplifica el uso de HTTP.

Así pues utilizando el endpoint /wp-json/wp/v2/users/me podemos crear una pequeña aplicación que nos confirme nuestra identidad de manera que sabremos que la comunicación con la API está siendo exitosa. El siguiente código ilustra cómo realizar la petición GET HTTP al endpoint para leer los datos de la respuesta.

Al ejecutar el comando desde nuestro terminal con php whoami.php obtendremos una salida similar a la siguiente:

Una vez hemos comprobado que todo funciona bien podríamos extraer una lista con los posts más recientes, para ello podemos sacar partido de los parámetros que nos permite enviar la API para modificar la respuesta. Haremos una petición GET a /wp-json/wp/v2/posts filtrando los post ya publicados, con 2 resultados por página y la primera página de resultados. Esto sería equivalente a la petición incluyendo el siguiente querystring: /wp-json/wp/v2/posts?status=publish&per_page=2&page=1, a continuación podemos ver el código resultante al enviar la petición con guzzle.

En este caso hemos utilizado el helper table de symfony/console para mostrar los resultados en una tabla de modo que el resultado de ejecutar nuestro comando será algo parecido a lo siguiente:

Hasta ahora hemos visto de qué manera podemos obtener información desde la API sea necesaria o no la autenticación, en el siguiente ejemplo vamos a crear un post enviando una petición POST con el título y el cuerpo de la publicación, si no incluimos estado WordPress por defecto lo dejará como borrador. Como podemos ver a continuación el código para automatizar la creación de artículos es muy sencillo y una vez creado nos notifica del id del post y su título.

Por último vamos a publicar esos post que hemos ido dejando como borradores. Para ello debemos combinar los comandos que hemos creado anteriormente como indica el código que sigue al párrafo. Primero obtendremos los post que estén como borradores utilizando status=draft y posteriormente uno a uno realizaremos peticiones POST a /wp-json/wp/v2/posts/POSTID cambiando el valor de status a publish.

Conclusión

Una de las grandes características de las API REST es su facilidad de uso, como hemos podido ver podemos ejecutar todas las operaciones básicas (incluyendo el borrado pese a no estar ejemplificado podemos consultarlo en la documentación y ver que no alberga ninguna complejidad extra) sobre los recursos de nuestro WordPress con código muy sencillo. Esto nos puede servir tanto para crear herramientas para migraciones como para integraciones en otros sistemas o la creación de herramientas propias que nos ayuden a automatizar nuestras tareas del día a día en la gestión de nuestro WordPress.

Podéis consultar el código completo del proyecto en el gist.