API REST WP Internos y Personalización

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

En la parte actual de la serie, analizaremos los aspectos internos de la API de REST de WP y cómo trabajan juntos para potenciar 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íficos, en el artículo actual, vamos a:

  • aprender sobre las clases y métodos internos de la API REST de WP
  • modificar la respuesta del servidor para los puntos finales predeterminados
  • Aprende a hacer campos personalizados editables.

Así que comencemos echando un vistazo a las partes internas de la API REST de WP..

Clases y métodos internos de la API REST de WP

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

  1. Clases de infraestructura: Estas son las clases fundamentales responsables de mantener unida la API. No realizan ninguna transformación de datos..
  2. 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 combinan la API REST son las siguientes:

  1. WP_REST_Server
  2. WP_REST_Request
  3. WP_REST_Response

WP_REST_Server

Esta es la clase principal de la API REST de WP que implementa el servidor REST mediante el registro de rutas, el servicio de solicitudes y la preparación de respuestas. Formatea los datos que deben pasarse al cliente y, en caso de error, prepara el error incluyendo el código de error y el cuerpo del mensaje. También comprueba la autenticación.

Hemos estado trabajando bastante con el / wp-json índice de punto final 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 atender solicitudes y preparar respuestas, el WP_REST_Server clase usa el WP_REST_RequestWP_REST_Response clases respectivamente.

WP_REST_Request

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

WP_REST_Response

los WP_REST_Response La clase, 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 punto final..

Clases de punto final

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

los WP_REST_Controller clase incluye métodos tales como obtiene el objeto(), create_item (), update_item ()Eliminar elemento(), etc., para realizar operaciones de CRUD. Estos métodos deben ser anulados 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..

Después de haber aprendido sobre las clases internas de la API REST de WP, echemos un vistazo a 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 y los métodos internos sobre los que se basa la API. Juntas, estas clases y métodos dirigen la API como un todo y brindan una forma para que los desarrolladores extiendan la API para dar cuenta de diferentes escenarios y casos de uso..

La API REST de WP expone los datos de una manera predecible. Esto incluye varios recursos como publicaciones, meta de publicación, páginas y usuarios, junto con sus propiedades estándar. Pero estos datos no siempre pueden ajustarse 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.

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

Del mismo modo, eliminar un campo predeterminado es altamente desaconsejable por la razón por la cual un cliente podría estar esperándolo. 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 vereditar.

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

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

Trabajando con el register_rest_field () Método

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

  1. $ tipo_objeto
  2. $ atributo
  3. $ args

los $ tipo_objeto el argumento 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 enviar, término, comentariousuario, Si necesitamos agregar un campo personalizado a un tipo de publicación personalizada, entonces $ tipo_objeto argumento sería el nombre del tipo de publicación.

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

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

  1. $ get_callback
  2. $ update_callback
  3. $ esquema

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. El último $ esquema clave 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 $ get_callback clave pero no la $ update_callback clave, se agregará la funcionalidad de recuperación, pero no se agregará la funcionalidad de actualización. Si omites el $ get_callback clave, el campo no se agregará a la respuesta en absoluto.

los register_rest_field () El método funciona modificando el $ wp_rest_additional_fields variable. Esta variable de la matriz contiene campos registrados por tipos de objetos que se devolverán en la respuesta del servidor. Cada vez que un campo es registrado por el register_rest_field () método, se añade a la $ wp_rest_additional_fields variable. Sin embargo, modificando el $ wp_rest_additional_fields La variable manualmente está fuertemente desaconsejada.

Agregando campos personalizados a la respuesta

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

Comenzamos creando un plugin simple. Así que crea una nueva carpeta llamada modificador de respuesta de reposo en tus / wp-content / plugins directorio. Crear un vacío index.php archivar y pegar en la siguiente definición de plugin:

los register_rest_field () método debe ser registrado en el rest_api_init acción. Por lo tanto, creamos una función llamada bs_add_custom_rest_fields () y atarlo a la rest_api_init gancho:

Tenga en cuenta que las etiquetas PHP de apertura no se requieren aquí, pero los he incluido para que la sintaxis se resalte correctamente.

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

function bs_add_custom_rest_fields () // esquema para el campo bs_author_name $ bs_author_name_schema = array ('description' => 'Nombre del autor de la publicación', 'type' => 'string', 'context' => array ('view') ); // registrar el campo bs_author_name 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 register_rest_field () método es el nombre del objeto para el que estamos modificando la respuesta. Ya que necesitamos modificar la respuesta para el enviar Objeto, 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 prefijar el nombre de un campo personalizado en la respuesta para asegurar la máxima compatibilidad hacia adelante y para que otros complementos no la anulen en el futuro. Por lo tanto, pasamos bs_author_name en el segundo argumento como el $ atributo 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 el $ get_callback$ update_callback teclas respectivamente. Pasamos el bs_get_author_name Funciona como el método de devolución de llamada de recuperación. Definiremos esta función en breve..

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

Para el $ esquema Clave, 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 el bs_get_author_name () función que actuará como la $ get_callback Método para nuestro campo personalizado. A continuación se muestra el código para esta función:

/ ** * Devolución de llamada para recuperar el nombre del autor * @param array $ object El objeto post actual * @param string $ field_name El nombre del campo * @param WP_REST_request $ request La solicitud actual * @return string El nombre del autor * / función bs_get_author_name ($ object, $ field_name, $ request) return get_the_author_meta ('display_name', $ object ['author']); 

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

  1. $ objeto: El objeto actual. En nuestro caso, es la publicación actual..
  2. $ field_name: El nombre del campo personalizado que se agrega.
  3. $ solicitud: El objeto de solicitud.

Estamos usando el $ autor propiedad de la $ objeto Argumento que contiene el id del post autor. Y usando el get_the_author_meta () función, recuperamos y devolvemos el nombre para mostrar del autor para la publicación actual.

Ahora que el campo está registrado, podemos enviar un OBTENER solicitud a la / wp / v2 / posts Ruta 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 enviemos un OPCIONES solicitud a la / wp / v2 / posts ruta:

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

Registro de un campo editable

Ahora registraremos un campo personalizado para el recuento de vistas de publicación. Solo nos ocuparemos del registro real del campo con WP REST API, dejando de lado la implementación para incrementar el número de conteo.

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

// esquema para el campo bs_post_views $ bs_post_views_schema = array ('description' => 'Recuento de vistas de publicaciones', 'type' => 'integer', 'context' => array ('view', 'edit')); // registrando el campo bs_post_views register_rest_field ('post', 'bs_post_views', array ('get_callback' => 'bs_get_post_views', 'update_callback' => bs_update_post_views ',' schema '=> $ bs_post.png.png)

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 el $ update_callback llave. Esta función es responsable de actualizar el valor del campo..

los $ contexto propiedad en el $ bs_post_views_schema matriz de esquema incluye dos valores para ver y editar. Inclusión del valor de edición en el $ contexto argumento asegura que la bs_post_views El campo se devuelve en la respuesta del servidor después de que se haya actualizado..

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

/ ** * Devolución de llamada para recuperar el recuento de vistas de publicación * @param array $ object El objeto de publicación actual * @param string $ field_name El nombre del campo * @param WP_REST_request $ request La solicitud actual * @return integer Número de visitas La cantidad de visitas * / función bs_get_post_views ($ object, $ field_name, $ request) return (int) get_post_meta ($ object ['id'], $ field_name, true);  / ** * Devolución de llamada para actualizar el recuento de vistas de publicación * @param mixed $ value El recuento de vistas de publicación * @param object $ object El objeto de la respuesta * @param string $ field_name Nombre del campo actual * @return bool | int * / función bs_update_post_views ($ value, $ object, $ field_name) if (! $ value ||! is_numeric ($ value)) return;  devolver update_post_meta ($ object-> ID, $ field_name, (int) $ value); 

El código es bastante simple ya que usa el get_post_meta ()update_post_meta () Métodos para recuperar y actualizar los valores respectivamente..

los bs_get_post_views () método primero recupera el valor meta para el bs_post_views meta clave 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:

  1. $ valor: El nuevo valor para el campo..
  2. $ objeto: Objeto actual de la respuesta.
  3. $ field_name: El nombre del campo que se está actualizando..

En el bs_update_post_views () Método, primero verificamos si el valor que se está pasando 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 update_post_meta () función que lo guarda en la base de datos después de que el tipo lo convierta en un entero válido.

Habiendo registrado el campo con éxito, probémoslo enviando un OBTENER solicitud:

$ GET / wp / v2 / posts

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

Como podemos ver en la imagen de arriba, el valor actual de la bs_post_views El campo es 0 para una publicación dada. Esto es porque el get_post_meta () El método está devolviendo una cadena vacía ya que no pudo encontrar un valor meta para el bs_post_views clave de metadatos y conversión de tipos de una cadena vacía en un entero en PHP da como resultado 0.

Podemos actualizar el bs_post_views campo enviando un ENVIAR solicitud a la / wp / v2 / posts / punto final El cuerpo JSON para la solicitud es el siguiente:

"bs_post_views": 4050

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

los bs_post_views el campo personalizado ahora está actualizado.

Tenga en cuenta que enviamos un cuerpo JSON a lo largo de la solicitud para actualizar el campo. El cuerpo de JSON incluía el nombre del campo.-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 que verifica un valor numérico en el bs_update_post_views () método de devolución de llamada.

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

 'Nombre del autor de la publicación', 'type' => 'string', 'context' => array ('view')); // registrar el campo bs_author_name register_rest_field ('post', 'bs_author_name', array ('get_callback' => 'bs_get_author_name', 'update_callback' => null, 'schema' => $ bs_author_name_schema)); // esquema para el campo bs_post_views $ bs_post_views_schema = array ('description' => 'Recuento de vistas de publicaciones', 'type' => 'integer', 'context' => array ('view', 'edit')); // registrando el campo bs_post_views register_rest_field ('post', 'bs_post_views', array ('get_callback' => 'bs_get_post_views', 'update_callback' => bs_update_post_views ',' schema '=> $ bs_post.png.png)  / ** * Devolución de llamada para recuperar el nombre del autor * @param array $ object El objeto post actual * @param string $ field_name El nombre del campo * @param WP_REST_request $ request La solicitud actual * @return string El nombre del autor * / function bs_get_author_name ($ object, $ field_name, $ request) return get_the_author_meta ('display_name', $ object ['author']);  / ** * Devolución de llamada para recuperar el recuento de vistas de publicaciones * @param array $ object El objeto de la publicación actual * @param string $ field_name El nombre del campo * @param WP_REST_request $ request La solicitud actual * @return integer Número de visitas La cantidad de visitas * / función bs_get_post_views ($ object, $ field_name, $ request) return (int) get_post_meta ($ object ['id'], $ field_name, true);  / ** * Devolución de llamada para actualizar el recuento de vistas de publicación * @param mixed $ value El recuento de vistas de publicación * @param object $ object El objeto de la respuesta * @param string $ field_name Nombre del campo actual * @return bool | int * / función bs_update_post_views ($ value, $ object, $ field_name) if (! $ value ||! is_numeric ($ value)) return;  devolver update_post_meta ($ object-> ID, $ field_name, (int) $ value); 

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

Solo el principio…

Aquí concluimos nuestro viaje de presentarnos a la API REST de WP. En esta serie, hemos cubierto conceptos bastante básicos como los métodos de autenticación y la recuperación, creación y actualización de datos. En esta última parte de la serie, examinamos brevemente las clases internas de la API REST de WP 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 REST de WP; de hecho, nunca se puede lograr en una sola serie. Pero, más bien, el propósito de esta serie era ponerlo en funcionamiento con esta nueva y fantástica adición y animarlo a jugar y experimentar por su cuenta. Espero que hayas encontrado esta serie cumpliendo su objetivo final..