Cree y obtenga puntos finales REST personalizados en bloques de Gutenberg

En esta publicación, intentaré crear una descripción general de cómo crear puntos finales de API REST personalizados y realizar solicitudes para ellos en un bloque de Gutenberg personalizado. Es decir, realizar solicitudes con fetchmétodos de información no disponible en los almacenes de datos registrados de WordPress.

Un recordatorio amistoso: la información más básica ya está disponible en los almacenes de datos de WordPress. Por ejemplo, las consultas básicas de publicaciones, páginas, tipos de publicaciones personalizadas, taxonomías, autores, medios y más están disponibles tal cual sin tener que crear sus propios puntos finales personalizados. Para acceder a estas tiendas, prefiere usar el módulo de datos básicos de WordPress (withSelecty select()). A continuación hay una parte del tutorial que profundiza en cómo hacerlo.

API REST de WordPress

Si no lo sabías ya; WordPress REST API es una interfaz JSON para enviar y recibir datos de su sitio de WordPress. Se puede utilizar externa o internamente. Con el editor de Gutenberg y el cambio a Javascript, los usos de la API REST definitivamente han aumentado. La API REST de WordPress tiene un montón de puntos finales que podemos usar. Vea una referencia completa sobre todos los extremos de la API REST aquí. Encontrará, por ejemplo, puntos finales para publicaciones y la mayoría de los demás contenidos internos, tanto para leer como para actualizar. Los desarrolladores de temas o complementos pueden registrar sus propios puntos finales personalizados.

Su sitio de WordPress tiene una URL API REST raíz, por defecto ubicada en <your domain>/wp-json. Por ejemplo, un WordPress local con la URL http://localhost/wordpress/puede acceder a la API REST en http://localhost/wordpress/wp-json. A partir de ahí, necesitamos agregar puntos finales. Con referencia a la referencia anterior de puntos finales, podemos recuperar una lista de las últimas publicaciones en el punto final /wp/v2/posts. Eso significa que si accede a http://localhost/wordpress/wp-json/wp/v2/postssu navegador, obtendrá una respuesta en formato JSON de las últimas publicaciones en su sitio de WordPress.

Se requiere una nota sobre los espacios de nombres. Una URL de API REST comienza con un espacio de nombres (‘ wp/v2‘ es el espacio de nombres de WordPress como se ve en las URL de ejemplo anteriores). Los espacios de nombres son un concepto para evitar conflictos en el núcleo de WordPress, los temas y los complementos que agregan puntos finales con el mismo nombre. Cree su propio espacio de nombres único, generalmente una forma de slug de su tema o nombre de complemento. Después del slug, una regla general es agregar el número de versión, que normalmente comienza en v1. Como ejemplo, el slug de mi tema es ‘ awhitepixel‘, por lo que si tuviera que crear puntos finales personalizados en mi tema, usaría el espacio de nombres ‘ awhitepixel/v1‘. Con este espacio de nombres podría registrar un punto final ‘ posts‘ y no causaría problemas a pesar de que es idéntico al nombre del punto final de WordPress.

Trabajar con la API REST en WordPress es un tema amplio con mucha buena información disponible. En esta publicación, me estoy enfocando en la usabilidad en el editor Gutenberg y cómo recuperarlos en Javascript.

Lo que haremos y lo que necesitamos

La facilidad de uso para solicitar información personalizada tiene una amplia gama de casos de uso, por lo que normalmente necesitará personalizar los ejemplos de código a continuación para que se ajusten a sus necesidades. Los datos pueden ser una consulta posterior personalizada, una consulta SQL personalizada o algo completamente diferente.

Cuando creamos un punto final personalizado, tenemos el control total de su retorno. Podemos realizar cualquier tipo de operaciones y consultas en WordPress/PHP y pasar esto como JSON. Y en nuestro bloque de Gutenberg podremos recuperar este retorno y hacer lo que queramos con él dentro de la editfunción del bloque. Por lo general, usaría los datos para presentar al usuario final una opción o información dentro del editor de bloques, pero también puede almacenar información en su bloque para su uso posterior. También puede crear sus propias tiendas personalizadas para estos datos, pero no explicaré cómo hacerlo.

Supongo que ya está familiarizado con la creación de bloques de Gutenberg personalizados, por lo que no lo analizaré en detalle aquí.

Creación de un punto final de API REST

El registro de un punto final de API REST personalizado se realiza en PHP. Agregaría este código en su tema functions.phpo en un código de complemento activo. Enganche una función a la acción rest_api_inity ejecute la función [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()para cada punto final que desee registrar.

Proporcione su espacio de nombres como primer parámetro, su ruta de punto final como segundo y una serie de configuraciones como tercer parámetro para register_rest_route(). El cuarto parámetro controla si desea anular o no una ruta existente; no es algo que veremos aquí. En la matriz para el tercer parámetro, como mínimo, debe establecer la propiedad ‘ callback‘ en una función que sea responsable de devolver los datos del punto final. Establecer ‘ method‘ también es común, por ejemplo, configurar su punto final en ‘ GET‘, ‘ POST‘, ‘ PUT‘, etc.

Comencemos con el registro de un punto final simple;

El espacio de nombres de mi tema es ‘ awhitepixel/v1‘ y estoy registrando un punto final ‘ mydata‘ dentro de este espacio de nombres. Esto significa que puedo acceder a mi API REST personalizada en http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.

Al registrar (o cambiar) las rutas de la API REST, deberá vaciar sus enlaces permanentes para que funcione. Puede hacerlo visitando Configuración > Enlaces permanentes y simplemente haga clic en Guardar.

El código anterior aún no funciona porque no he definido la función establecida como devolución de llamada: awhitepixel_rest_route_mydata. La función de devolución de llamada recibe un parámetro; una matriz de datos con información y argumentos pasados ​​desde la solicitud. Finalmente, debe considerar cuidadosamente el retorno de su función de devolución de llamada.

En primer lugar, siempre debe devolver algo desde la devolución de llamada de su punto final. Cualquier devolución se convertirá automáticamente en JSON por WordPress. Esto significa que puede devolver prácticamente cualquier forma de datos en su función; una cadena, un valor nulo, una matriz o una [WP_Error](https://developer.wordpress.org/reference/classes/wp_error/)instancia. También puede optar por devolver un [WP_REST_Response](https://developer.wordpress.org/reference/classes/wp_rest_response/)objeto para tener más control, por ejemplo, sobre el código de estado o la información del encabezado. Recomiendo envolver el retorno en la función [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()para asegurar que su respuesta sea una respuesta REST válida.

Definamos nuestra función de devolución de llamada y devolvamos una cadena simple como inicio;

function awhitepixel_rest_route_mydata($data) {
    $response = 'Hello there!';
    return rest_ensure_response($response);
}

Con el código anterior (y los enlaces permanentes descargados), ahora puedo ir a la URL http://localhost/wordpress/wp-json/awhitepixel/v1/mydata.

A partir de aquí, podemos agregar cualquier tipo de código en nuestra función de devolución de llamada para generar los datos adecuados para devolver. Puede consultar el contenido de WordPress con, por ejemplo [WP_Query](https://developer.wordpress.org/reference/classes/wp_query/), realizar consultas en la base de datos o solicitar datos externos. Esta parte depende de ti.

Ahora, pasemos al lado opuesto; cómo hacer las solicitudes.

Hacer solicitudes de API REST en Javascript

La realización de una solicitud REST se realiza comúnmente con [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)Javascript. WordPress proporciona su propio contenedor fetchque simplifica las solicitudes de la API REST de WordPress; [wp.apiFetch](https://developer.wordpress.org/block-editor/packages/packages-api-fetch/). Esto es lo que usaré en mi bloque de Gutenberg personalizado. Tenga en cuenta que fetchlas solicitudes devuelven una "promesa", por lo que debemos encadenar una .then()para manejar la devolución de la solicitud real. El uso base es algo como esto;

apiFetchnos permite proporcionar una pathpropiedad en lugar de construir la URL completa. Todo lo que necesitamos proporcionar es el espacio de nombres y el punto final, y apiFetchlo agregaremos a la URL raíz de la API REST de WordPress. Dentro de la .then()función tenemos acceso a los datos que ya están convertidos a JSON. Es aquí donde harías algo con los datos. Por lo general, almacenaría los datos devueltos, por ejemplo, en el estado del componente.

editA continuación se muestra un ejemplo de un componente de bloque de Gutenberg personalizado. Está basado en clases para poder usarlo statepara almacenar los datos devueltos por la solicitud de la API REST. Esto también nos permite ejecutar la solicitud componentDidMount()cuando se monta por primera vez (consulte la documentación de React sobre métodos de ciclo de vida ). Todo esto proporciona un ejemplo simple para que entiendas el concepto básico; no como una receta para hacerlo exactamente así. Podría considerar usar ganchos React y componentes funcionales o construir un componente de orden superior en su lugar.

El ejemplo anterior es un componente basado en clases que se proporciona a la editfunción del bloque en registerBlockType(). Establece un objeto de estado de una matriz para contener los datos (esto depende de los datos que devuelva, obviamente) y un booleano de estado para saber cuándo ha regresado la solicitud asíncrona. Una vez que el componente está montado (renderizado por primera vez), ejecuta la función para realizar la apiFetchsolicitud. Establecemos la ruta al punto final que registramos en PHP arriba. El método es GET de forma predeterminada, por lo que no es necesario especificarlo en apiFetch. Y dentro .then()de la función, cuando la solicitud está lista, actualizamos el estado del componente con los datos devueltos.

Obviamente, la función de procesamiento de su bloque haría más con los datos devueltos. Es posible que desee proporcionar los datos al usuario de alguna manera presentando una lista para elegir. Todo depende de qué tipo de datos sean y para qué quieras usarlos.

Pasar argumentos al punto final

En algunos casos, necesitamos pasar algunos argumentos al punto final. Los usos comunes son pasar una ID después del punto final; por ejemplo http://localhost/wordpress/wp-json/wp/v2/posts/14, devolvería el ID de publicación 14.

Esto es bastante simple y se hace agregando un patrón de búsqueda de expresiones regulares al punto final al registrarlo. Se requiere cierto conocimiento de expresiones regulares para crear patrones complejos, pero a continuación se muestra un ejemplo que coincide con un número y le asigna el nombre ‘id’. Nombrar las coincidencias nos da los medios para acceder a la variable en nuestra función de devolución de llamada. Déjame mostrarte lo que quiero decir.

Registremos una nueva ruta de punto final. Usamos el mismo punto final que usamos antes (‘ awhitepixel/v1/mydata‘), pero para esta ruta agregamos una coincidencia de expresiones regulares para un número al final.

El patrón de expresiones regulares (?P<id>[d]+)parece críptico, pero será bastante claro con una comprensión básica de las expresiones regulares. La [d]+parte coincide con cualquier número (0-9) 1 o más veces. Las partes (?P<id>y )son para hacer coincidir un grupo con nombre. En este caso, el nombre del grupo es id, pero puede nombrar a su(s) grupo(s) como desee.

Puede elegir dirigir este punto final a una función de devolución de llamada separada, pero he elegido usar la misma función para manejar ambas /mydatasolicitudes /mydata/<ID>. Esto significa que puedo en mi función de devolución de llamada hacer:

function awhitepixel_rest_route_mydata($data) {
    if ($data['id']) {
        $response = 'Create return for ID: '. $data['id'];
    } else {
        $response = 'Create general return (no ID provided)';
    }
    return rest_ensure_response($response);
}

Recuerde que el parámetro de la función de devolución de llamada contiene los argumentos devueltos. Debido a que nombré a mi grupo coincidente ‘ id‘, el valor coincidente estará accesible en $data['id']. Y, por último, como utilizo la misma función para gestionar solicitudes con y sin ID, puedo cambiar fácilmente entre dos devoluciones diferentes.

Con esto (y los enlaces permanentes actualizados), obtendré estas respuestas para mis terminales personalizados: