Guía detallada para crear y obtener puntos finales personalizados de la API REST de WP

Esta publicación mostrará cómo crear puntos finales REST de WordPress personalizados y diferentes métodos para realizar solicitudes a ellos. Habrá ejemplos tanto en PHP, jQuery y Vanilla Javascript.

Supongo que ya está familiarizado con lo que es la API REST de WP, pero aquí hay un breve resumen. WordPress REST API es una interfaz JSON para enviar y recibir datos de su sitio de WordPress. Puede acceder a los puntos finales (rutas/URL específicas) tanto externa como internamente. WordPress ya tiene un montón de puntos finales disponibles, por ejemplo, para obtener publicaciones, categorías, buscar en el sitio y más. Vea una descripción general de los puntos finales predeterminados de WordPress aquí. Pero los desarrolladores son totalmente libres de crear sus propios puntos finales personalizados utilizando esta API, ya sea para realizar acciones o para obtener datos.

Comenzaremos con el primer paso; que está creando puntos finales personalizados. Si solo te interesa cómo hacer solicitudes, salta a la segunda parte.

Crear puntos finales personalizados

El registro de puntos finales personalizados se realiza en PHP. Puede agregar el código al functions.phparchivo de código de su tema o de un complemento activo. Haga una función enlazada rest_api_inity use la función [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()para cada punto final que desee agregar.

Como primer parámetro register_rest_route(), debe proporcionar un espacio de nombres único para asegurarse de que sus puntos finales no entren en conflicto con ningún otro. Usa el slug de tu tema o plugin. Es una práctica común incluir un /seguido de un número de versión para su código. Como ejemplo, usaré el espacio de nombres awhitepixel/v1. El segundo parámetro es la ruta (que sigue al espacio de nombres). Finalmente, puede proporcionar opcionalmente una matriz como tercer parámetro con opciones. En esta matriz, puede, por ejemplo, definir el método de solicitud (GET, POST o cualquier otro), definir parámetros y, lo que es más importante, definir la función que se ejecutará cuando se solicite ese punto final.

Como mínimo, debe proporcionar los argumentos ‘método’ y ‘devolución de llamada’ (que es la función para manejar los datos del punto final) como tercer parámetro. Para ‘método’ puede configurarlos como ‘ GET', 'POST', 'PUT'o cualquier otro método de solicitud válido (o una matriz de múltiples), pero recomiendo usar los valores predeterminados de WordPress para esto. Son los siguientes:

• WP_REST_Server::READABLE método ‘ GET‘
• WP_REST_Server::EDITABLE métodos ‘ POST‘, ‘ PUT‘ y ‘ PATCH‘
• WP_REST_Server::DELETABLE método ‘ DELETE‘
• WP_REST_Server::ALLMETHODS todos los métodos anteriores

Vamos a crear un punto final personalizado básico al que se pueda acceder mediante solicitudes GET:

En la línea #2hemos definido nuestro punto final personalizado como ‘ awhitepixel/v1/getsomedata‘. La URL completa sería la URL raíz de la API REST de WordPress con el prefijo, que es <yourdomain>/wp-json. Por lo tanto, la URL completa del punto final anterior sería ‘ <yourdomain>/wp-json/awhitepixel/v1/getsomedata‘. En línea #4, proporcionamos un nombre de función como devolución de llamada, que agregaremos en breve.

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

Todavía no hemos definido la función de devolución de llamada, que es la función para el código que maneja la reacción de usar este punto final. Debe devolver una respuesta válida de REST (en JSON), por lo que deberá devolver algo aunque se supone que el punto final no debe devolver datos. Puede usar la función [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()función o crear una instancia de WP_REST_Responseobjeto como retorno de la devolución de llamada. Como parámetro de la función de devolución de llamada, obtenemos un WP_REST_Requestobjeto que contiene toda la información sobre la solicitud, incluidos los parámetros. Vamos a crear una función de devolución de llamada simple que simplemente envíe un texto como respuesta:

function awhitepixel_rest_route_getsomedata( $request) {
    $response = 'Hello there!';
    return rest_ensure_response( $response );
}

Esta es la forma más básica de escribir una devolución de llamada. La función rest_ensure_response()se asegura de que cualquier dato que proporcionemos (la cadena) se convierta en una respuesta válida REST. Obviamente, querrá agregar más código aquí, ya sea para hacer algo en WordPress o para obtener y enviar datos.

Con el código anterior (registrando el punto final y la función de devolución de llamada) puede intentar ir a la URL en su navegador y ver qué obtiene. (Recuerde vaciar sus enlaces permanentes). Ir a <domain>/wp-json/awhitepixel/v1/getsomedataen el navegador mostrará la cadena "¡Hola!".

Aceptar parámetros

Es muy común y útil permitir que los puntos finales acepten parámetros. Por ejemplo, si su sitio tiene, por ejemplo, datos de productos, querrá un punto final en el que pueda proporcionar una ID de producto para obtener los datos de ese producto. Hay dos maneras de hacerlo. La forma más común es usar la cadena de consulta GET (que se agregan después de la URL después de un ?, separados por &el formato clave=valor. Por ejemplo, ‘ <endpoint>/product/?product_id=14‘). Alternativamente, puede definir un patrón de URL "más bonito", donde los parámetros son parte de la ruta. Por ejemplo ‘ <endpoint>/product/14/‘. Sin embargo, este último método requiere cierto conocimiento de las expresiones regulares. El método que elija depende de usted, demostraré ambos a continuación.

OBTENER parámetros

Definir posibles parámetros GET para su punto final es usar la argstecla ‘ ‘ en register_rest_route()el tercer parámetro. Para cada parámetro que desee permitir, defina el valor clave (en el ejemplo anterior ‘ product_id‘) y una serie de opciones para ese parámetro. Como opciones puedes definir el formato del parámetro (si espera por ejemplo un número o una cadena) y también decidir si ese parámetro es requerido o no.

Como ejemplo, queremos permitir que nuestro punto final acepte ‘ product_id‘ como un número no requerido.

Si define un parámetro como verdadero en required, WordPress se encargará de devolver una respuesta de error 400. Del mismo modo, si pasa un formato no válido, por ejemplo, "hola" como valor a un parámetro que espera un número.

En la línea #15de la función de devolución de llamada, verá cómo obtener el valor del parámetro de la solicitud; usando el método get_param()en el objeto pasado WP_REST_Request. Como ejemplo mostraré diferentes respuestas dependiendo de si product_idse proporcionó o no (recuerda que lo hemos definido como opcional). La lógica de modificar su código de acuerdo con los parámetros provistos depende completamente de usted y su proyecto. Puede tener menos puntos finales que acepten muchos parámetros o muchos más puntos finales separados para cada caso específico.

Con el código anterior, obtendré "¡Hola!" cuando visito <yourdomain>/awhitepixel/v1/getsomedatay "Devolver datos de producto para ID 14" cuando voy a <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.

Parámetros como parte de la ruta

Si desea permitir que los parámetros formen parte de la ruta en lugar de la cadena de consulta GET, puede hacerlo. Luego proporcionará un patrón de expresiones regulares en la ruta: el segundo parámetro para register_rest_route().

La creación de patrones de expresiones regulares puede parecer bastante críptica, pero dado que es un tema completo, encontrará fácilmente ejemplos para casos específicos si lo busca en Google. Mostraré un ejemplo de cómo definir una expresión regular que acepta un número de cualquier longitud;

Como puede ver en la línea n. ° 2, agregué el patrón de expresiones regulares (?P<product_id>[d]+)al final. Estos patrones significan que debemos recopilar un número (d) de cualquier longitud (+) y asignar el valor recopilado a la clave del parámetro product_id. Y en nuestra función de devolución de llamada usamos exactamente el mismo método que usamos cuando configuramos los parámetros GET; get_param()en el WP_REST_Requestobjeto proporcionado a la función.

Con el código anterior (después de vaciar los enlaces permanentes) podemos visitar la URL <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14para obtener nuestra respuesta. Este método ciertamente da como resultado URL "más bonitas", pero el código puede volverse más difícil de leer y corregir errores. Cualquiera que sea el método que elija depende de usted.

Devolver la respuesta adecuada

Anteriormente mencioné brevemente cómo la función de devolución de llamada debe devolver una respuesta REST adecuada. Hasta ahora hemos usado el más simple rest_ensure_response(). Pero a veces es posible que desee tener más control sobre la devolución de su punto final. Por ejemplo, es posible que desee controlar el código de estado de respuesta HTTP. Supongamos que está creando un punto final en el que puede proporcionar una identificación de producto y obtener datos para ese producto. Pero si ese ID de producto no existe, o cualquier otro parámetro causa confusión, es posible que desee devolver un código de estado de, por ejemplo, 400 (Solicitud incorrecta) o 404 (No encontrado). O tal vez 500 (error del servidor). Pasar siempre 200 (Éxito) incluso si la solicitud fue incorrecta puede causar problemas al final del remitente.

Entonces recomendaría su función de devolución de llamada que devuelve un WP_REST_Responseobjeto. Con este objeto puedes controlar varias cosas, incluido el código de estado. ¡Es más fácil de lo que piensas! En la forma más simple, crearía una nueva instancia de WP_REST_Response, proporcionaría una matriz de los datos para devolver como primer parámetro y el código de estado como segundo parámetro. Como ejemplo:

En el ejemplo anterior almacenamos el retorno de la awhitepixel_get_product()función en una variable. Esta función no existe y debe reemplazarla con la función que debe obtener (o realizar) las acciones que desea en su proyecto. Pero digamos que la función devuelve una matriz vacía y eso significa que algo salió mal (por ejemplo, el producto no existía). Luego, podríamos devolver un WP_REST_Responseobjeto con el código de estado 400 y, opcionalmente, un mensaje como datos que explican por qué falló (línea #5-9). De lo contrario, devolvemos los datos con el código de estado 200 Éxito (línea #10).

Envío de solicitudes a puntos finales (personalizados)

Pasemos al otro lado, la parte de envío: cómo enviar solicitudes a nuestros puntos finales personalizados. Normalmente, enviaría solicitudes de API REST de WP usando Javascript y aquí encontrará ejemplos del uso de jQuery, la biblioteca de WordPress y Javascript estándar. Es poco común, pero posible, realizar una solicitud REST con PHP también, por lo que también he incluido un ejemplo de eso.

Lo primero que debe tener en cuenta es que obviamente necesita conocer la URL completa para enviar una solicitud. No recomiendo codificar el dominio (antes del punto final), ya que hay varias formas de obtener esto si su Javascript está funcionando dentro de WordPress. En versiones anteriores de WordPress, necesitaría usar [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()PHP y pasar la URL REST principal como una variable global de Javascript. Pero los ejemplos a continuación muestran una forma más nueva y mejor de obtener la URL raíz REST del sitio de WordPress.

Otra cosa a tener en cuenta es que para su proyecto probablemente envolvería las solicitudes como resultado de alguna acción. Para simplificar las cosas, estoy preparando todas las solicitudes en DOM, por lo que debe asegurarse de incluir el código de solicitud, por ejemplo, como resultado de que un visitante haga clic en un botón.

Usando jQuery

Si tiene y desea usar la biblioteca jQuery, puede usar su [$.ajax](https://api.jquery.com/jquery.ajax/)()función.

Pero primero una nota sobre las dependencias de su archivo Javascript. Obviamente, su script necesitaría una 'jquery'dependencia para ponerlo en cola. Pero para acceder fácilmente a la URL raíz REST de WordPress, agregue otra dependencia; ‘solicitud de wp-api’. Esto garantiza que la variable Javascript wpApiSettings.rootesté disponible y contenga la URL raíz de la API REST. Aquí hay un ejemplo de cómo pondría en cola su secuencia de comandos para ilustrar esta dependencia;

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'jquery', 'wp-api-request' ], 
        null, 
        true
    );
} );

La línea #5es la interesante; donde definimos tanto jQuery wp-api-requestcomo dependencia. Luego, en nuestro archivo Javascript, podemos realizar una solicitud de API REST de WP de la siguiente manera:

( function( $) {
    // Send request
    $.ajax( {
        url: wpApiSettings.root + 'awhitepixel/v1/getsomedata',
        method: 'GET',
        data: {
            product_id: 14
        },
        success: function( data) {
            console.log( data );
        }
    } );
} )( jQuery );

Esto es tan básico como parece. Usamos $.ajax()para enviar una solicitud GET a la URL definida. Como URL, usamos wpApiSettings.rootpara obtener la URL raíz de la API REST y luego agregamos el punto final deseado después de ella; en nuestro caso, el punto final personalizado que creamos anteriormente. Opcionalmente podemos pasar parámetros en ‘datos’. El ejemplo anterior pasa product_idcon el valor 14 al punto final. Finalmente en la successfunción recibimos la solicitud (exitosa) como parámetro y somos libres de hacer lo que queramos con ella. En el ejemplo anterior, simplemente lo imprimimos en la consola.

Uso de la biblioteca de WordPress (no jQuery)

Si su sitio de WordPress no tiene o puede usar la biblioteca jQuery, puede usar la biblioteca Javascript de WordPress para realizar fácilmente una solicitud de API REST. La función es la que está disponible en el espacio de nombres apiFetchglobal de WordPress. es un método contenedor para la función estándar del navegador (que se muestra a continuación).wp``wp.apiFetch()``fetch()

Nuestro Javascript necesitará la dependencia ‘wp-api’ para usar wp.apiFetch(). Por ejemplo, podríamos poner en cola el script de esta manera:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api' ], 
        null, 
        true
    );
} );

Encontrará la dependencia crítica en la línea #5. Con esto nos hemos asegurado de que nuestro archivo Javascript wp.apiFetch()esté disponible. Aquí hay un ejemplo básico en su uso:

Tenga en cuenta que la línea #9-13es solo lógica para ejecutar la función después de que DOM esté listo.

Un beneficio de usar wp.apiFetch()sobre lo normal fetch()es que podemos usar ‘ruta’ que requiere solo el punto final, en lugar de ‘url’ que requiere la URL completa. Otro beneficio es que la primera "cadena" .then()devuelve los datos ya formateados en JSON. Cuando usa el original .fetch(), necesita más cadenas ".then()". Eche un vistazo al siguiente ejemplo ("Uso de Javascript vainilla") para ver a qué me refiero.

Tenga en cuenta que fetch()(y como consecuencia wp.apiFetch()) no proporciona una forma "limpia" de pasar parámetros. Tendremos que construir manualmente la cadena de consulta GET en ‘ruta’, como lo hice anteriormente: '../getsomedata?product_id=14'.

Si está interesado en cómo incorporar wp.apiFetchy personalizar puntos finales en un bloque de Gutenberg, he escrito un tutorial separado sobre esto:

Usando vainilla Javascript

Como ejemplo final de los métodos de Javascript para enviar una solicitud a la API REST de WP, existe una forma pura y sencilla, que no es de WordPress, usando fetch(). Tenga en cuenta que uso la variable global de WordPress para obtener la URL raíz REST. Si está agregando este script fuera de WordPress, probablemente necesite codificar la URL completa.

Como todavía quiero acceder a la variable global para la URL raíz de WP REST, agrego 'wp-api-request'dependencia a mi función de puesta en cola de Javascript, así:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api-request' ], 
        null, 
        true
    );
} );

Y luego, en nuestro archivo Javascript, un ejemplo más básico sería:

Como se mencionó anteriormente ("Usar la biblioteca de WordPress") .fetch()no admite una forma agradable y limpia de proporcionar parámetros. Por lo tanto, deberá crear manualmente la cadena de consulta ("?product_id=14") en la URL.

Tenga en cuenta que la solicitud de búsqueda no se devuelve directamente con los datos, sino que devuelve una promesa. Es por eso que necesitamos encadenar ” .then()" antes de que podamos manejar los datos. Si esto no le resulta familiar, le recomiendo que busque cómo trabajar con fetch(): hay muchas explicaciones y ejemplos en Google que pueden explicarlo mejor que yo.

Si desea verificar el código de estado de respuesta REST a su solicitud, puede hacerlo así;

En el ejemplo anterior al registrar puntos finales personalizados, mencioné cómo podría devolver diferentes códigos de estado HTTP. El código anterior muestra un ejemplo de cómo verificar el código de estado de la respuesta, que está disponible en la propiedad del objeto devuelto .status. En el ejemplo anterior, verifico si el código de estado es diferente a 200 (Éxito) en la línea #5. Solo si el código de estado era 200, convierto el retorno de datos de la promesa en JSON (línea #9).

Usando PHP

Es menos común, pero aún posible, realizar una solicitud REST internamente en WordPress usando PHP. Así es cómo.

Para enviar una solicitud de API REST de WP en PHP, creamos un WP_REST_Requestobjeto (exactamente como lo que se pasa a nuestra función de devolución de llamada anteriormente en esta publicación). En esta instancia de objeto, definimos el método (por ejemplo, GET) y la ruta del punto final. Opcionalmente también podemos añadir parámetros. Luego usamos la función de WordPress [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()con esta instancia de solicitud. Finalmente obtenemos la respuesta con la [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()función disponible en WP_REST_Server'la clase s.

La llamada a la función set_query_params()(línea #3-5) es opcional y solo necesaria si desea pasar parámetros. Siguiendo el hilo rojo en esta publicación, incluiré un ejemplo de cómo pasar el parámetro de la función a la clave del parámetro REST product_id.

La línea #6es donde enviamos la solicitud. Y en línea #7devolvemos los datos de la respuesta. Entonces, si tuviéramos que llamar a esta función PHP, por ejemplo awp_do_php_rest_request( 14 ), obtendríamos la respuesta que definimos en ese punto final (una matriz con una cadena si todavía usa el mismo ejemplo que el comienzo de esta publicación).