API WP REST: Internos y personalización

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

En la parte anterior de la serie, aprendimos a crear, actualizar y eliminar contenido de forma remota a través de la API WP REST. Nos permite crear aplicaciones independientes de la plataforma que funcionan a la perfección con un back-end con tecnología de WordPress, proporcionando una experiencia enriquecedora para el usuario.

En la parte actual de la serie, veremos los aspectos internos de la API WP REST y cómo trabajan juntos para alimentar la API. Después de eso, aprenderemos a modificar las respuestas del servidor para que los puntos finales predeterminados incluyan campos personalizados.

Para ser específico, en el artículo actual, vamos a:

aprende sobre las clases internas y los métodos de la API WP REST
modificar la respuesta del servidor para puntos finales predeterminados
aprende cómo hacer que los campos personalizados sean editables

Comencemos por echar un vistazo a las partes internas de la API WP REST.

Clases internas y métodos de la API WP REST

Las clases en la API REST WP se pueden dividir en las siguientes dos categorías:

Clases de infraestructura: estas son las clases fundamentales responsables de mantener unida la API. No realizan ninguna transformación de datos.
Clases de punto final: Estas clases son responsables de realizar operaciones de CRUD en recursos como publicaciones, páginas, usuarios, comentarios, etc.

Echemos un vistazo a las clases individuales de cada una de las dos categorías anteriores.

Clases de Infraestructura

Las tres clases de infraestructura que en conjunto potencian la API REST son las siguientes:

WP_REST_Server
WP_REST_Request
WP_REST_Response

WP_REST_Server

Esta es la clase principal de la API REST de WP que implementa el servidor REST registrando rutas, atendiendo solicitudes y preparando respuestas. Formatea los datos que se pasarán al cliente y, en caso de error, prepara el error incluyendo el código de error y el cuerpo del mensaje. También verifica la autenticación.

Hemos trabajado mucho con el punto final índice /wp-json para verificar todas las capacidades y rutas admitidas para un sitio. El método get_index(), que es responsable de recuperar el índice del sitio, también se encuentra en esta clase.

Para servir solicitudes y preparar respuestas, la clase WP_REST_Server usa las clases WP_REST_Request y WP_REST_Response, respectivamente.

WP_REST_Request

La clase WP_REST_Request implementa el objeto de solicitud para la API WP REST. Contiene datos de la solicitud, como encabezados y cuerpo de la solicitud, y se pasa a la función de devolución de llamada por la clase WP_REST_Server. También comprueba si los parámetros que se pasan a lo largo de la solicitud son válidos y realiza la desinfección de datos cuando sea necesario.

WP_REST_Response

La clase WP_REST_Response, como su nombre lo indica, implementa el objeto de respuesta. Contiene los datos necesarios, como el código de estado de respuesta y el cuerpo de respuesta.

Veamos ahora las clases de endpoint.

Clases de Endpoint

Las clases de punto final en la API REST WP son responsables de realizar operaciones CRUD. Estas clases incluyen WP_REST_Posts_Controller, WP_REST_Taxonomies_Controller, WP_REST_Users_Controller, etc. Todas estas clases de punto final extienden una única clase abstracta WP_REST_Controller que proporciona un patrón consistente para modificar datos.

La clase WP_REST_Controller incluye métodos tales como get_item(), create_item(), update_item(), delete_item(), etc., para realizar operaciones CRUD. Estos métodos deben ser reemplazados por subclases implementando su propia abstracción para recuperar, crear, actualizar y modificar datos.

Puede encontrar más información sobre estas clases y sus métodos internos en la documentación oficial.

Tras conocer las clases internas de la API WP REST, veamos cómo podemos modificar las respuestas del servidor para que los puntos finales predeterminados incluyan campos personalizados.

Modificar las respuestas del servidor

En la sección anterior, analizamos las clases internas y los métodos sobre los que se basa la API. En conjunto, estas clases y métodos dirigen la API como un todo y proporcionan una forma para que los desarrolladores amplíen la API para tener en cuenta diferentes escenarios y casos de uso.

La API WP REST expone los datos de una manera predecible. Esto incluye varios recursos como publicaciones, publicaciones, páginas y usuarios, junto con sus propiedades estándar. Pero estos datos no siempre se ajustan a las necesidades de cada sitio o usuario de WordPress. Por lo tanto, la API REST de WP proporciona una forma de modificar los datos que el servidor devuelve para cada una de las rutas predeterminadas.

El método register_rest_field() proporciona una forma de agregar o actualizar campos en la respuesta de un objeto. Sin embargo, la API nunca fomenta el cambio de un campo a partir de una respuesta, ya que podría presentar problemas de compatibilidad para los clientes que esperan una respuesta estándar del servidor. Entonces, si necesita cambiar un campo, debería considerar duplicar el campo con el valor deseado.

Del mismo modo, eliminar un campo predeterminado es muy desaconsejable por el motivo que un cliente podría estar esperando. Si necesita un subconjunto más pequeño de la respuesta devuelta por el servidor, debe crear contextos adicionales además de los contextos predeterminados como view o edit.

Sin embargo, podemos agregar de manera segura un campo a la respuesta devuelta por el servidor para uno o varios objetos. Estos campos pueden contener cualquier valor que vaya desde meta o meta del usuario a cualquier otro valor arbitrario.

En la siguiente sección, trabajaremos con el método register_rest_field() para agregar campos personalizados a la respuesta devuelta por el servidor para el objeto post.

Trabajando con el método `register_rest_field()`

Como se mencionó anteriormente, el método register_rest_field() se puede usar para agregar o actualizar campos en la respuesta devuelta por el servidor. Este método acepta tres argumentos:

$object_type
$attribute
$args

El argumento $object_type puede ser una cadena o una matriz que contiene los nombres de todos los objetos para los que queremos agregar el campo. Estos objetos pueden ser de post, term, comment, user, etc. Si necesitamos agregar un campo personalizado a un tipo de publicación personalizado, entonces el argumento $object_type sería el nombre del tipo de publicación.

El argumento $attribute es el nombre del campo personalizado. Este nombre aparecerá en la respuesta del servidor como una clave junto con su valor.

La matriz $args es una matriz asociativa que puede contener las siguientes tres claves:

$get_callback
$update_callback
$schema

Los valores de las dos primeras claves son los nombres de los métodos que se utilizan para obtener o actualizar el valor del campo personalizado. La última clave $schema define el método o la variable que se utiliza para definir el esquema para el campo personalizado.

Todas las claves anteriores son opcionales, pero si no se agregan, la capacidad no se agregará. Por ejemplo, si define la clave $get_callback pero no la clave $update_callback, se agregará la funcionalidad de recuperación pero no se agregará la funcionalidad de actualización. Si omite la clave $get_callback, el campo no se agregará a la respuesta en absoluto.

El método register_rest_field() funciona modificando la variable $wp_rest_additional_fields. Esta variable de matriz contiene campos registrados por tipos de objetos que se devolverán en la respuesta del servidor. Cuando un campo es registrado por el método register_rest_field(), se agrega a la variable $wp_rest_additional_fields. Sin embargo, no se recomienda modificar la variable $wp_rest_additional_fields manualmente.

Agregar campos personalizados a la respuesta

Habiéndonos familiarizado con el método register_rest_field(), ahora podemos modificar la respuesta para el objeto post. Un caso de uso típico aquí sería la adición de un campo de nombre para mostrar del autor, que comúnmente se necesita cuando se enumeran las publicaciones en una página de índice. Dado que la respuesta estándar no incluye este campo, podemos usar el método register_rest_field() para incluirlo en la respuesta.

Comenzamos creando un plugin simple. Así que crea una nueva carpeta llamada rest-response-modifier en tu directorio /wp-content/plugins. Cree un archivo index.php vacío y péguelo en la siguiente definición de complemento:

<?php
/**
 * Plugin Name: REST Response Modifier
 * Description: A very simple plugin for development and testing purpose to modify the response of the REST API plugin.
 * Author: Bilal Shahid
 * Author URI: http://imbilal.com
 */

El método register_rest_field() debe registrarse en la acción rest_api_init. Por lo tanto, creamos una función llamada bs_add_custom_rest_fields() y la vinculamos al gancho rest_api_init:

<?php
add_action( 'rest_api_init', 'bs_add_custom_rest_fields' );

function bs_add_custom_rest_fields() {
    
}

Tenga en cuenta que las etiquetas PHP de apertura <?php no son necesarias aquí, pero las he incluido para que la sintaxis se destaque correctamente.

Dentro de la función bs_add_custom_rest_fields(), podemos usar el método register_rest_field() para incluir un campo para el nombre del autor:

function bs_add_custom_rest_fields() {
    // schema for the bs_author_name field
    $bs_author_name_schema = array(
        'description'   => 'Name of the post author',
        'type'          => 'string',
        'context'       =>  array( 'view' )
    );
    
    // registering the bs_author_name field
    register_rest_field(
        'post',
        'bs_author_name',
        array(
            'get_callback'      => 'bs_get_author_name',
            'update_callback'   => null,
            'schema'            => $bs_author_name_schema
        )
    );
}

Como se mencionó en la sección anterior, el primer argumento en el método register_rest_field() es el nombre del objeto para el cual estamos modificando la respuesta. Como necesitamos modificar la respuesta para el objeto post, pasamos lo mismo que el primer argumento.

El segundo argumento en el código anterior es el nombre del campo que aparecerá en la respuesta. Siempre es una buena práctica colocar el nombre de un campo personalizado en la respuesta para garantizar la máxima compatibilidad con versiones anteriores y que no quede anulado en el futuro por otros complementos. Por lo tanto, pasamos bs_author_name en el segundo argumento como el $attribute del campo personalizado.

El tercer y último argumento en el código anterior es una matriz para los métodos de devolución de llamada y el esquema. Esta matriz contiene el nombre de los métodos de devolución de llamada para la recuperación y actualización del campo personalizado en las claves $get_callback y $update_callback, respectivamente. Pasamos la función bs_get_author_name como el método de devolución de llamada de recuperación. Definiremos esta función en breve.

Para la clave $update_callback, pasamos null ya que este es un campo de solo lectura y no necesitamos actualizar el nombre del autor para una publicación.

Para la clave $schema, pasamos una matriz llamada $bs_author_name_schema. Esta matriz contiene varias propiedades para el campo, como el tipo de datos, el contexto y la descripción.

Lo único que necesitamos definir ahora es la función bs_get_author_name() que actuará como el método $get_callback para nuestro campo personalizado. Debajo está el código para esta función:

/**
 * Callback for retrieving author name
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return string                           The name of the author
 */
function bs_get_author_name( $object, $field_name, $request ) {
    return get_the_author_meta( 'display_name', $object['author'] );
}

El método $get_callback recibe tres argumentos para lo siguiente:

$object: el objeto actual. En nuestro caso, es la publicación actual.
$field_name: el nombre del campo personalizado que se agrega.
$request: el objeto de solicitud.

Estamos utilizando la propiedad $author del argumento $object que contiene la identificación del autor de la publicación. Y al usar la función get_the_author_meta(), recuperamos y devolvemos el nombre para mostrar del autor para la publicación actual.

Ahora que el campo está registrado, podemos enviar una solicitud GET a la ruta /wp/v2/posts para ver si funciona correctamente:

Aquí está la respuesta en Postman:

Este campo personalizado recién registrado también aparecerá en la respuesta del servidor, junto con su esquema, cuando enviamos una solicitud de OPTIONS a la ruta /wp/v2/posts:

Por lo tanto, se ha registrado correctamente un campo personalizado para la propiedad del nombre del autor. Pero este campo es de solo lectura, ya que no podemos actualizarlo enviando una solicitud POST. En la siguiente sección, registraremos un campo editable para contar las visitas posteriores.

Registrando un campo editable

Ahora registraremos un campo personalizado para el recuento de visitas posteriores. Solo trataremos el registro real del campo con la API REST WP, omitiendo la implementación para incrementar el número de conteo.

A continuación se muestra el código para el registro de campo personalizado bs_post_views junto con su esquema:

// schema for bs_post_views field
$bs_post_views_schema = array(
    'description'   => 'Post views count',
    'type'          => 'integer',
    'context'       =>	array( 'view', 'edit' )
);

// registering the bs_post_views field
register_rest_field(
    'post',
    'bs_post_views',
    array(
        'get_callback'      => 'bs_get_post_views',
        'update_callback'   => 'bs_update_post_views',
        'schema'            => $bs_post_views_schema
    )
);

El código es similar al que escribimos en la sección anterior, excepto que ahora incluye un método de devolución de llamada bs_update_post_views para la clave $update_callback. Esta función es responsable de actualizar el valor del campo.

La propiedad $context en la matriz de esquema $ bs_post_views_schema incluye dos valores para view y edit. La inclusión del valor de edición en el argumento $context garantiza que el campo bs_post_views se devuelva en la respuesta del servidor después de que se haya actualizado.

Los métodos de devolución de llamada y actualización son los siguientes:

/**
* Callback for retrieving post views count
* @param  array             $object         The current post object
* @param  string            $field_name     The name of the field
* @param  WP_REST_request   $request        The current request
* @return integer                           Post views count
*/
function bs_get_post_views( $object, $field_name, $request ) {
    return (int) get_post_meta( $object['id'], $field_name, true );
}

/**
* Callback for updating post views count
* @param  mixed     $value          Post views count
* @param  object    $object         The object from the response
* @param  string    $field_name     Name of the current field
* @return bool|int
*/
function bs_update_post_views( $value, $object, $field_name ) {
    if ( ! $value || ! is_numeric( $value ) ) {
        return;
    }

    return update_post_meta( $object->ID, $field_name, (int) $value );
}

El código es bastante simple ya que utiliza los métodos get_post_meta() y update_post_meta() para recuperar y actualizar los valores, respectivamente.

El método bs_get_post_views() recupera primero el metavalor de la clave meta bs_post_views y lo convierte en un entero antes de devolverlo.

El método de devolución de llamada pasado en $update_callback recibe tres argumentos para lo siguiente:

$value: el nuevo valor para el campo.
$object: objeto actual de la respuesta.
$field_name: el nombre del campo que se está actualizando.

En el método bs_update_post_views(), primero verificamos si el valor que se pasa no está vacío y es un valor numérico. Si no, volvemos sin hacer nada.

Si el valor es numérico, lo pasamos a la función update_post_meta() que lo guarda en la base de datos luego de ingresarlo en un entero válido.

Habiendo registrado el campo con éxito, probemos enviando una solicitud GET:

$ GET /wp/v2/posts

A continuación se muestra una respuesta de muestra para la solicitud anterior:

Como podemos ver en la imagen de arriba, el valor actual del campo bs_post_views es 0 para una publicación determinada. Esto se debe a que el método get_post_meta() está devolviendo una cadena vacía ya que no pudo encontrar un valor meta para la clave meta bs_post_views y al convertir una cadena vacía en un entero en PHP se obtiene 0.

Podemos actualizar el campo bs_post_views enviando una solicitud POST al punto final /wp/v2/posts/<id>. El cuerpo JSON para la solicitud es el siguiente:

{
    "bs_post_views": 4050
}

Si la solicitud es exitosa, el servidor devuelve un código de estado 200 - OK junto con el objeto de publicación actualizado que también incluye el campo bs_post_views:

El campo personalizado bs_post_views ahora se ha actualizado.

Tenga en cuenta que enviamos un cuerpo JSON junto con la solicitud para actualizar el campo. El cuerpo JSON incluía el campo nombre-bs_post_views-con un valor entero de 4050. Si intentamos enviar un valor no numérico, digamos "abc1234", el campo no se actualizará ya que tenemos una condición para verificar un valor numérico en el método de devolución de llamada bs_update_post_views().

A continuación se muestra el código fuente completo para el complemento:

<?php
/**
 * Plugin Name: REST Response Modifier
 * Description: A very simple plugin for development and testing purpose to modify the response of the REST API plugin.
 * Author: Bilal Shahid
 * Author URI: http://imbilal.com
 */

add_action( 'rest_api_init', 'bs_add_custom_rest_fields' );

/**
 * Function for registering custom fields
 */
function bs_add_custom_rest_fields() {
    // schema for the bs_author_name field
    $bs_author_name_schema = array(
        'description'   => 'Name of the post author',
        'type'          => 'string',
        'context'       =>	array( 'view' )
    );
    
    // registering the bs_author_name field
    register_rest_field(
        'post',
        'bs_author_name',
        array(
            'get_callback'      => 'bs_get_author_name',
            'update_callback'   => null,
            'schema'            => $bs_author_name_schema
        )
    );
    
    // schema for bs_post_views field
    $bs_post_views_schema = array(
        'description'   => 'Post views count',
        'type'          => 'integer',
        'context'       =>	array( 'view', 'edit' )
    );
    
    // registering the bs_post_views field
    register_rest_field(
        'post',
        'bs_post_views',
        array(
            'get_callback'      => 'bs_get_post_views',
            'update_callback'   => 'bs_update_post_views',
            'schema'            => $bs_post_views_schema
        )
    );
}

/**
 * Callback for retrieving author name
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return string                           The name of the author
 */
function bs_get_author_name( $object, $field_name, $request ) {
    return get_the_author_meta( 'display_name', $object['author'] );
}

/**
 * Callback for retrieving post views count
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return integer                          Post views count
 */
function bs_get_post_views( $object, $field_name, $request ) {
    return (int) get_post_meta( $object['id'], $field_name, true );
}
/**
 * Callback for updating post views count
 * @param  mixed    $value          Post views count
 * @param  object   $object         The object from the response
 * @param  string   $field_name     Name of the current field
 * @return bool|int
 */
function bs_update_post_views( $value, $object, $field_name ) {
    if ( ! $value || ! is_numeric( $value ) ) {
        return;
    }

    return update_post_meta( $object->ID, $field_name, (int) $value );
}

Eso es todo para modificar las respuestas del servidor para los puntos finales API predeterminados. Apenas hemos arañado la superficie para modificar la API REST, ya que proporciona mucha más flexibilidad que la simple modificación de las respuestas del servidor. Esto incluye agregar soporte para el tipo de contenido personalizado mediante controladores personalizados y espacios de nombres, y registrar rutas personalizadas para exponer y modificar datos. Trataremos de cubrir estos temas avanzados en futuros artículos.

Solo el principio...

Aquí concluimos nuestro viaje de introducción a la API WP REST. En esta serie, hemos cubierto conceptos bastante básicos como métodos de autenticación y recuperación, creación y actualización de datos. En esta última parte de la serie, examinamos brevemente las clases internas de la API WP REST y luego aprendimos a modificar las respuestas del servidor para los puntos finales predeterminados.

Nunca fue el propósito de esta serie cubrir todos y cada uno de los aspectos de la API WP REST, de hecho, nunca se puede lograr en una sola serie. Pero más bien, el propósito de esta serie era ponerlo en marcha con esta nueva adición fantástica y alentarlo a jugar y experimentar por su cuenta. Espero que hayas encontrado que esta serie cumple su objetivo final.