API WP REST: Recuperación de datos

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

En las partes anteriores de la serie, hemos estado analizando qué es la API REST de WP y cómo puede ayudarnos a crear mejores aplicaciones usando el back end de WordPress.

Luego observamos dos formas de configurar la autenticación en el servidor para generar solicitudes autenticadas. El primero es el método de autenticación básica, que es útil en entornos de desarrollo y permite el prototipado rápido, ya que no requiere mucho tiempo para su configuración. El segundo método de autenticación es OAuth 1.0a, que se recomienda para entornos de producción, ya que es mucho más seguro que el método de autenticación básico.

Ahora que hemos aprendido cómo configurar la autenticación, estamos listos para generar solicitudes autenticadas para liberar toda la potencia de la API WP REST. Utilizaremos la autenticación básica en toda esta serie debido a su facilidad de uso, pero se recomienda que utilice la autenticación OAuth 1.0a, tal como lo proporciona el complemento OAuth 1.0a, para sus servidores de producción.

En la parte actual de la serie, obtendremos nuestra primera experiencia práctica con el complemento WP REST API. Lo haremos:

analizar la estructura de una solicitud GET
mira cómo la solicitud OPTIONS auto-documenta la API
enviar solicitudes al servidor para la recuperación de datos
analizar la respuesta del servidor que incluye propiedades, esquemas y enlaces

Comencemos por analizar la estructura de una simple solicitud GET.

Anatomía de una solicitud `GET`

Antes de profundizar en los detalles de la recuperación de datos con la API WP REST, tenemos que familiarizarnos con la sintaxis de una solicitud que se envía al servidor. Esto sentará una base sólida para nuestras futuras interacciones con la API WP REST.

Considere la siguiente solicitud enviada al servidor:

1	$ GET https://localserver/wp-json/wp/v2/posts

El tipo de solicitud que estamos enviando es GET: uno de los seis verbos HTTP que vimos en la parte inicial de esta serie. Una solicitud GET se utiliza para recuperar datos del servidor. Por lo tanto, cuando se ejecuta en el servidor, la solicitud anterior recupera una colección de todos los objetos de publicación en forma de datos JSON.

Teniendo en cuenta el URI de solicitud, podemos dividirlo en las siguientes partes:

http://localserver/: la URL de mi servidor de desarrollo local. Podría ser cualquier URL dependiendo de dónde esté ubicada su instalación de WordPress.
/wp-json: es el prefijo del punto final de la API WP REST.
/wp: el espacio de nombres del complemento WP REST API.
/v2: es la versión del complemento WP REST API.
/posts: es el recurso que queremos recuperar del servidor.

El espacio de nombres evita la anulación que podría producirse al ejecutar varios complementos, cada uno de los cuales proporciona su propia capa de abstracción para la API RESTful. Por lo tanto, cada abstracción funciona en su propio límite sin afectar los métodos y propiedades que pertenecen a alguna otra abstracción.

El espacio de nombre y la versión no estaban presentes en la versión heredada 1.2 del complemento. Entonces en la versión heredada, la solicitud anterior sería así:

1	$ GET http://localserver/wp-json/posts

Pero no hablaremos de compatibilidad con versiones anteriores aquí. Si desea conocer todos los cambios que ocurrieron entre la versión 1.xy 2.x, puede encontrarlos en la página oficial.

Además de recuperar una colección de recursos (publicaciones) usando el URI anterior, también podemos recuperar un recurso específico mencionando su ID:

1	$ GET /wp/v2/posts/100

La solicitud anterior devolverá un objeto de publicación mientras busca un recurso de publicación que tenga una ID de 100.

En otras ocasiones, también necesitamos buscar publicaciones que cumplan algunos criterios específicos. Para ello, la API WP REST proporciona una forma de utilizar la sintaxis filter[]:

1	$ GET /wp/v2/posts?filter[cat]=1

Al enviar la solicitud anterior, podemos recuperar todas las publicaciones que pertenecen a una categoría de ID 1. La sintaxis del filtro puede ser particularmente útil al consultar publicaciones o navegar entre diferentes recursos, p. publicaciones y categorías, usando sus relaciones.

Finalmente, cuando se trata de argumentos que toman arrays como entrada en la sintaxis filter[], podemos anexar un conjunto vacío de corchetes para expresar arrays de esta manera:

1	$ GET /wp/v2/posts?filter[category__and][]=1&filter[category__and][]=2

La sintaxis anterior es equivalente a la siguiente WP_Query():

<?php

$query = new WP_Query( array(
    'category__in'  => array( 1, 2 )
) );

Por lo tanto, la solicitud GET anterior recuperará una lista de publicaciones que pertenecen a ambas categorías con una ID de 1 y 2. La misma sintaxis también se puede usar para argumentos de matriz que tengan más de dos elementos. Tenga en cuenta que el uso del parámetro category__and requiere autenticación de usuario con privilegios edit_posts.

Examinaremos la sintaxis de filter[] con más detalle en una sección posterior.

Ahora que hemos aprendido cómo formatear una solicitud GET y proporcionar sus parámetros, es hora de echar un vistazo a la solicitud de OPTIONS. Una solicitud OPTIONS hace que sea más fácil navegar a través de la API y en realidad sirve como una forma de auto-documentación para hacer que la API sea más accesible al documentar todos los métodos HTTP disponibles en un punto final y, a su vez, los argumentos que admiten.

Navegando a través de la API usando la solicitud de `OPTIONS`

Como se mencionó anteriormente, la solicitud OPTIONS puede ser extremadamente útil para explorar la API. Menciona todos los puntos finales que pertenecen a una ruta determinada y proporciona una lista de parámetros que estos puntos finales admiten para las operaciones CRUD.

Enviemos una solicitud OPTIONS a la ruta /wp/v2/posts para verificar qué puntos finales admite y qué parámetros podemos pasar a lo largo de la solicitud GET para consultar datos:

1	$ curl -X OPTIONS wp/v2/posts

He utilizado cURL para enviar la solicitud anterior, pero puede usar cualquier herramienta de su elección, incluido Postman. Asegúrese de incluir la ruta completa a la ruta anterior, incluida la ruta de su servidor.

1	{
2	"namespace": "wp/v2",
3	"methods": [...],
4	"endpoints": [...],
5	"schema": {...},
6	"_links": {...}
7	}

La solicitud OPTIONS anterior a la ruta /wp/v2/posts devuelve datos en el formato JSON que contiene cinco propiedades:

namespace
methods
endpoints
schema
_links

1	{
2	"namespace": "wp/v2",
3	....
4	}

La propiedad namespace identifica el espacio de nombres del complemento actual. En nuestro caso, es wp/v2, que significa la versión 2 de la API WP REST. Ya hemos analizado el espacio de nombres y el propósito al que sirve en la sección anterior.

1	{
2	...
3	"methods": [
4	"GET",
5	"POST"
6	],
7	...
8	}

La propiedad de métodos methods contiene una matriz de todos los métodos admitidos por la ruta actual. Al observar la respuesta que devolvió la solicitud anterior, está claro que la ruta /wp/v2/posts admite dos métodos, a saber, GET y POST. Significa que podemos usar la ruta /wp/v2/posts para recuperar publicaciones, así como también para crear una nueva publicación. Trataremos el método POST en la próxima parte de esta serie, así que centrémonos en el método GET por el momento.

La siguiente propiedad-endpoints-contiene una matriz de los puntos finales soportados para la ruta actual. Esta propiedad está directamente vinculada a la propiedad methods mencionada anteriormente, ya que enumera los puntos finales para los métodos admitidos.

1	{
2	...
3	"endpoints": [
4	{
5	"methods": [
6	"GET"
7	],
8	"args": {...}
9	},
10	{
11	"methods": [
12	"POST"
13	],
14	"args": {...}
15	}
16	],
17	...
18	}

La propiedad de endpoints contiene valores de objetos que a su vez contienen dos propiedades, a saber, methods y args. La propiedad de methods contiene una matriz de métodos HTTP, y la siguiente propiedad de argumentos args contiene todos los argumentos admitidos para estos métodos. Estos son los argumentos que enviamos a lo largo de la solicitud en forma de parámetros de URI.

Al observar los argumentos respaldados por el método GET, encontramos nueve argumentos que incluyen context, page, per_page, etc. Estos objetos de argumento contienen dos propiedades, required y default. La propiedad required indica si el argumento es obligatorio y la propiedad predeterminada default representa el valor predeterminado del argumento.

"methods": [
        "GET"
    ],
"args": {
    "context": {
        "required": false,
        "default": "view"
    },
    "page": {
        "required": false,
        "default": 1
    },
    "per_page": {
        "required": false,
        "default": 10
    },
    "filter": {
        "required": false
    }
}

La propiedad schema en la respuesta devuelta documenta todas las propiedades del recurso actual. El esquema define una estructura para los datos en el formato JSON. El formato de esquema utilizado en la API WP REST se basa en el borrador 4 de las especificaciones del esquema JSON.

La última propiedad _links contiene una matriz de objetos que contienen los enlaces de los recursos asociados. La clave en el objeto especifica el tipo de relación (por ejemplo, author, collection, self, comments, etc.), cuyo valor es el enlace a ese recurso asociado. Este estándar de enlace se basa en HAL (Hypertext Application Language). Puede encontrar más información sobre HAL leyendo las especificaciones escritas por Mike Kelley.

De manera similar, podemos enviar una solicitud OPTIONS a otras rutas, incluidas las de usuarios, comentarios, medios, páginas, etc., para verificar sus métodos y argumentos admitidos. Las solicitudes OPTIONS son su mejor amigo cuando trabaja con la API WP REST.

La API WP REST proporciona otra forma de evaluar la disponibilidad de la API enviando una solicitud GET a la ruta del índice /wp-json. Esto mostrará una lista de todas las rutas y sus endpoints junto con sus métodos y argumentos admitidos.

1	$ curl -X GET http://wordpress-server/wp-json

La solicitud anterior devolverá un objeto de respuesta que contiene una propiedad de rutas de la siguiente manera:

Esta característica es inmensamente poderosa ya que enumera todas las rutas y sus métodos y argumentos admitidos, eliminando así la necesidad de documentar externamente todo esto. Nos referiremos a este objeto de respuesta cuando realice operaciones CRUD en diferentes recursos.

Tras examinar nuestras opciones para explorar la API, comencemos a trabajar con la API REST de WP para recuperar datos del servidor.

Trabajando con publicaciones

Por ahora, nos hemos familiarizado con la solicitud de OPTIONS, que es una forma autoevaluada de evaluar la disponibilidad de la API. También vimos cómo muestra los métodos y argumentos admitidos para una ruta determinada. Usando este conocimiento, ahora estamos listos para recuperar diferentes recursos del servidor usando la API WP REST.

El recurso con el que comenzaremos es el recurso Posts, ya que es el componente principal de WordPress. Nos ocuparemos de recuperar publicaciones usando diferentes filtros. Al aplicar este conocimiento, podrá consultar las publicaciones utilizando la API REST de WP tal como lo hace con la clase WP_Query().

A lo largo de esta serie, hemos estado trabajando con el recurso Posts para mostrar solicitudes de ejemplo y sus respuestas, y ya sabemos cómo recuperar la publicación de publicaciones y una publicación individual por su ID. Entonces no cubriremos eso de nuevo. En cambio, veremos algunas formas más avanzadas de recuperar publicaciones utilizando los parámetros de nivel superior y la sintaxis de filter[]

Trabajando con parámetros de nivel superior

La API WP REST expone algunas de las variables de consulta más utilizadas para las publicaciones directamente en el endpoint GET. Estos parámetros son:

context: el alcance de la solicitud. Los valores posibles podrían ser view, embed o edit.
page: la página actual de la colección de publicaciones.
per_page: Número total de publicaciones por página.
search: la consulta de búsqueda. Limite los resultados a la cadena coincidente.
author: la identificación del autor. Se usa para limitar los resultados que pertenecen a un autor específico.
exclude: una matriz de ID de publicación para excluir de los resultados de búsqueda.
include: limite los resultados para publicar los ID especificados en este conjunto.
offset: Compensa los resultados de búsqueda por número especificado.
order: el orden de la colección. Puede ser asc o desc.
orderby: atributo de clasificación de la colección. Los valores posibles pueden ser id, title o slug.
slug: limita los resultados a una publicación que tenga un slug específico.
status: se usa para limitar la recopilación de las publicaciones que tienen un estado particular.

El parámetro context se usa para buscar publicaciones según el alcance en el que trabajemos. Si solo estamos publicando publicaciones en alguna página de índice, entonces estamos en condiciones de usar el contexto view. Pero si estamos recuperando publicaciones para editarlas, entonces necesitamos usar el contexto edit:

1	$ GET /wp/v2/posts?context=edit

El parámetro de contexto edit introduce un campo raw adicional en campos como title, content, excerpt, etc. El valor de este campo raw puede repetirse en el editor para editar el contenido.

El uso del contexto edit requiere que se autentique como usuario con privilegios edit_posts.

Al usar embed como el valor del parámetro context, se obtiene la colección de las publicaciones con un subconjunto mínimo de sus propiedades.

Los otros parámetros mencionados anteriormente son bastante autoexplicativos, y puede jugar con ellos en su cliente HTTP.

Estos fueron los parámetros básicos que le permiten consultar las publicaciones basadas en ciertos criterios. Para reducir nuestras capacidades de consulta, la API REST de WP proporciona la sintaxis de filter[] que admite un subconjunto de los argumentos WP_Query ().

Usando el sintaxis `filter[]`

Además de recuperar una colección de publicaciones utilizando algunos parámetros básicos de nivel superior, la API REST WP expone algunas de las variables WP_Query() utilizando la sintaxis filter[] Al usar esta sintaxis, podemos consultar las publicaciones de la misma manera que lo hacemos al trabajar con la clase WP_Query().

Los parámetros de paginación son los más importantes de todos los filtros, ya que se usan ampliamente en las páginas de la lista de publicaciones. Los parámetros de paginación nos permiten mostrar un número específico de publicaciones por página y navegar a un número específico de páginas que contienen publicaciones.

De forma predeterminada, una solicitud GET recupera una colección de 10 publicaciones por página. Veamos cómo podemos enviar una solicitud GET para recuperar solo cinco publicaciones por página:

1	$ GET /wp/v2/posts?filter[posts_per_page]=5

La solicitud anterior usa la variable posts_per_page con la que puede estar familiarizado si ha trabajado con WP_Query().

El parámetro paged se utiliza junto con el parámetro posts_per_page y se usa para navegar a un número específico de páginas. Después de haber recuperado cinco publicaciones por página, haríamos la siguiente solicitud para navegar a la segunda página:

1	$ GET /wp/v2/posts?filter[posts_per_page]=5&filter[paged]=2

Los filtros posts_per_page y paged pueden ser extremadamente útiles cuando se trabaja para crear paginación en las páginas de listado usando la API WP REST. Estos dos parámetros son equivalentes a los parámetros page y per_page. Por lo tanto, la siguiente solicitud hace el mismo trabajo que la anterior:

1	$ GET /wp/v2/posts?per_page=5&page=2

Además de la colección de publicaciones que devuelve la solicitud anterior, el servidor también devuelve un número de encabezados con una respuesta que contiene información útil, incluida la cantidad total de publicaciones y el número de páginas. Estos valores están contenidos en los encabezados de respuesta X-WP-TotalPages y X-WP-Total.

Los encabezados de respuesta X-WP-TotalPages y X-WP-Total son extremadamente útiles al crear paginación usando la API WP REST, ya que enumeran el número total de páginas y el número total de publicaciones, respectivamente.

Además de los filtros de paginación, el otro uso más importante de la sintaxis filter[] es poder consultar las publicaciones por sus fechas. Para este propósito, la sintaxis filter[] admite ocho parámetros, los mismos que los de la clase WP_Query():

year: el año de cuatro dígitos (por ejemplo, 2015 o 2016)
monthnum: El número del mes de 1 a 12
m: año-mes de seis dígitos (por ejemplo, 201601)
w: la semana del año de 0 a 53
day: el día del mes de 1 a 31
hour: la hora del día de 0 a 23
minute: el minuto de la hora de 0 a 60
second: el segundo del minuto de 0 a 60

Entonces, si estamos buscando las publicaciones publicadas en la fecha 2015-10-15 (aaaa / mm / dd), esto se puede lograr con la siguiente consulta:

1	$ GET /wp/v2/posts?filter[year]=2015&filter[monthnum]=10&filter[day]=15

Se puede preparar una consulta similar con la ayuda de los parámetros anteriores si necesitamos reducir nuestra búsqueda a la hora exacta y los minutos.

Ya hemos visto en una sección previa de este tutorial cómo podemos obtener publicaciones que pertenecen a una categoría específica o categorías múltiples utilizando los parámetros filter[cat] y filter[category__and]. Ahora usaremos el parámetro filter[category__in] para mostrar las publicaciones que pertenecen a categorías que tienen una identificación de 5 y 6:

1	$ GET /wp/v2/posts?filter[category__in][]=5&filter[category__in][]=6

La solicitud anterior recuperará una lista de todas las publicaciones pertenecientes a categorías que tengan una identificación de 5 y 6.

El efecto opuesto se puede lograr utilizando el parámetro filter[category__not_in] de la siguiente manera:

1	$ GET /wp/v2/posts?filter[category__not_in][]=5&filter[category__not_in][]=6

Esto recuperará una lista de publicaciones sin incluir todas las publicaciones pertenecientes a categorías que tengan una ID de 5 o 6.

Se podría escribir más sobre el uso de la sintaxis filter[], pero no cubriré todo eso aquí. Puede encontrar una lista de todas las variables de consulta admitidas por la sintaxis filter[] en la documentación oficial de la versión 1 del complemento. Una gran parte de esta información sigue siendo válida con la versión 2 de la API WP REST, pero todavía falta en algunas áreas. En el momento de escribir este tutorial, la documentación oficial de la versión 2 no dice nada sobre la sintaxis filter[] y la consulta vars que admite, pero podemos esperar ver mejoras en la documentación oficial en un futuro próximo ya que hay una cantidad de personas (incluyéndome a mí) que contribuyen al desarrollo y documentación de los complementos.

Ahora que hemos analizado las diferentes opciones al consultar las publicaciones con la ayuda de la API WP REST, estamos listos para seguir avanzando en nuestro viaje y buscar otros recursos compatibles con la API WP REST.

Trabajando con revisiones de publicaciones, categorías, etiquetas y meta

Las revisiones de publicaciones proporcionan una forma de ver y restaurar las ediciones realizadas en una publicación. La API WP REST proporciona una forma de ver todas las revisiones de una publicación consultando el endpoint /posts/<id>/revisions. Por lo tanto, para una publicación determinada que tenga una ID de 10, todas las revisiones se pueden recuperar enviando la siguiente solicitud:

1	$ GET /wp/v2/posts/10/revisions

La solicitud anterior devolverá una matriz que contiene objetos de revisión. El objeto revisiones contiene un subconjunto de propiedades encontradas en el objeto post. A continuación se muestra un ejemplo de objeto de revisión en Postman:

Se puede recuperar una revisión específica dado que conocemos su id. Entonces, una revisión que tenga una ID de 2 con una publicación que tenga una ID de 10 se puede recuperar con el siguiente objeto:

1	$ GET /wp/v2/posts/10/revisions/2

La solicitud anterior devolverá un único objeto de revisión.

Además de las revisiones posteriores, las categorías para una publicación específica pueden recuperarse mediante la siguiente solicitud:

1	$ GET /wp/v2/categories?post=<post_id>

Y para las etiquetas, utilizamos la siguiente solicitud:

1	$ GET /wp/v2/tags?post=<post_id>

Con <post_id> es el ID de la publicación.

Si necesitamos recuperar post meta para la publicación con una ID de 10, enviamos la siguiente solicitud como usuario autenticado:

1	$ GET /wp/v2/posts/10/meta

Esto devolverá una matriz de metaobjetos.

Tenga en cuenta que para trabajar con meta y meta de la página en WP REST API, debe tener el plugin complementario instalado, disponible en GitHub, por parte del equipo WP REST API.

Trabajando con otros recursos

Hasta ahora, hemos obtenido una base bastante sólida para trabajar con la API WP REST para recuperar datos. Ya hemos analizado la solicitud de opciones y cómo nos ayuda a explorar la API sin necesidad de documentación externa.

Siempre puede enviar una solicitud de OPTIONS a un recurso en particular y verificar qué puntos finales y parámetros admite. Si necesita enumerar todas las rutas que proporciona la API WP REST, puede enviar una solicitud GET al punto final del índice en /wp-json, como aprendimos hacer al comienzo de este tutorial.

Teniendo en cuenta esta ventaja de auto-documentación, no creo que tengamos que explorar cada recurso individual en este tutorial, ya que ahora puede hacerlo por su cuenta.

¿Qué pasa después?

En este extenso tutorial, aprendimos a explorar la API utilizando la solicitud OPTIONS, así como a recuperar datos del servidor mediante la API WP REST. Acabamos de ver algunos recursos, incluidas publicaciones, revisión de publicaciones y metadatos, ya que no pudimos cubrir todos los recursos admitidos en un solo tutorial. Pero ahora debería poder explorar la API por su cuenta utilizando las técnicas que aprendimos en este tutorial.

WordPress tiene una economía increíblemente activa. Existen temas, complementos, bibliotecas y muchos otros productos que lo ayudan a construir su sitio y proyecto. La naturaleza de código abierto de la plataforma también la convierte en una excelente opción desde la que puede mejorar sus habilidades de programación. Cualquiera que sea el caso, puede ver todo lo que tenemos disponible en Envato Marketplace.

En la próxima entrega de esta serie, aprenderemos a realizar las otras tres operaciones de CRUD, es decir, crear, actualizar y eliminar recursos. Así que estad atentos...