REST API de WP: Creación, actualización y eliminación de datos

() translation by (you can also view the original English article)

En la parte anterior de esta serie, analizamos cómo podemos usar la REST API de WP para recuperar contenido del servidor. Aprendimos a recuperar contenido para diferentes recursos, incluyendo entradas, metadatos de entradas, etiquetas, categorías, etc. Esta es una potente característica ya que este contenido se puede utilizar en cualquier lugar dentro o fuera de WordPress.

También aprendimos acerca de la solicitud OPTIONS que autodocumenta la API enumerando todas las rutas, sus puntos de conexión y sus respectivos argumentos. Esto disminuye la necesidad de confiar en una documentación externa para la API y permite que los cambios se descubran con bastante rapidez en caso de que la API haya sido actualizada o modificada.

Después de haber examinado estas características, ahora, en el tutorial actual centraremos nuestra atención en las otras tres operaciones de CRUD, es decir, crear, actualizar y eliminar datos mediante la REST API de WP.

En este tutorial, vamos a:

analizar qué recursos admiten métodos de creación, actualización y eliminación
aprender a crear, actualizar y eliminar recursos
buscar formas de enviar datos junto con la solicitud para crear un recurso
analizar la respuesta del servidor y los diferentes códigos de respuesta

Así que comencemos analizando qué recursos admiten los métodos de creación, actualización y eliminación mediante la REST API de WP.

Comprobar métodos de creación, actualización y eliminación en las rutas

Antes de profundizar directamente en la creación y actualización de datos con la REST API de WP, necesitamos analizar qué rutas admiten métodos de creación y actualización. Para ello, comprobamos las rutas y la propiedad methods en sus puntos de conexión o endpoints. Esto se puede hacer enviando una solicitud independiente OPTIONS a rutas individuales, pero una manera más conveniente consiste enviar una solicitud GET a la ruta de índice /wp-json como hicimos en la parte anterior de esta serie.

El envío de una solicitud GET a la ruta /wp-json devuelve un objeto que contiene todas las rutas y sus puntos de conexión en la propiedad routes.

Es en estas rutas individuales podemos comprobar si un recurso específico admite los métodos POST, PUT, y DELETE. Comencemos analizando el recurso Posts.

El recurso Posts expone datos con las dos siguientes rutas:

1	/wp/v2/posts
2	/wp/v2/posts/(?P<id>[\d]+)

La primera ruta apunta a la recopilación del objeto post y su propiedad method de la siguiente forma:

1	"methods": [
2	"GET",
3	"POST"
4	],

Esta propiedad methods muestra que la ruta /posts admite los métodos GET y POST para recuperar y crear datos respectivamente.

Para la ruta /posts/(?P<id>[\d]+), que apunta a un único recurso Posts, la propiedad methods es la siguiente:

"methods": [
    "GET",
    "POST",
    "PUT",
    "PATCH",
    "DELETE"
],

Como se puede ver en el anterior código, la ruta /posts/(?P<id>[\d]+) admite los métodos GET, POST, PUT, PATCH y DELETE.

Al examinar las dos rutas anteriores, podemos concluir que la ruta /posts admite la recuperación y creación de recursos. ¿Y la ruta /posts/(?P<id>[\d]+) admite la recuperación de recursos, así como la actualización y eliminación. Aunque admite el método POST, esta ruta no admite la creación de recursos como puedes ver en el ejemplo que viene a continuación.

Por lo tanto, las rutas que apuntan a un único recurso no se pueden usar para crear contenido, aunque admiten el método POST. Esto se debe a que, para estas rutas, los métodos POST, PUT y PATCH se usan para actualizar el contenido de la REST API de WP.

Para concluir esta sección, vamos a resumir los conceptos que hemos aprendido aquí:

Podemos comprobar qué rutas admiten los métodos GET, POST y DELETE enviando una solicitud OPTIONS.
Las rutas que apuntan a una sola entidad no se pueden usar para crear contenido. Se utilizan para actualizar el contenido, aunque admiten el método POST.

Después de haber analizado diferentes rutas, ahora estamos listos para crear contenido mediante la REST API de WP y comenzaremos a explorar el recurso Posts.

Creación y actualización de una entrada

Vamos a crear una entrada enviando una solicitud de prueba desde Postman o cualquier otro cliente HTTP. Para ello, activa el cliente HTTP y envía una solicitud POST a la ruta /posts. Pero antes de eso, recuerda que la creación, eliminación y actualización de recursos requiere la autenticación como usuario con derechos edit_posts. Así que usaremos el método básico de autenticación que aprendimos en la segunda parte de esta serie.

Inicialmente, para la comprobación, enviamos un cuerpo de solicitud vacío junto a la solicitud:

1	$ POST /wp/v2/posts

El servidor devolverá un error 400 - Bad Request, ya que faltaban los argumentos necesarios en el cuerpo de la solicitud. El servidor devolverá la siguiente respuesta:

La respuesta indica que el contenido (content), el título (title) o el extracto (excerpt) son necesarios para crear un objeto post. Estos argumentos se pueden enviar junto a la solicitud, en el cuerpo de la solicitud de cualquiera de las tres maneras siguientes:

Como un objeto JSON
Mediante el uso de formularios
Como parámetros de URL

El uso de cualquiera de estos métodos es cuestión de preferencias, y los examinaremos más de cerca en este mismo tutorial más adelante. Pero ahora vamos a usar el primer método para crear una entrada.

Para enviar argumentos como un objeto JSON en Postman, cambia a la pestaña Body y selecciona el botón de opción raw. A continuación, en el menú desplegable de la derecha, selecciona la opción JSON (application/json). En la siguiente área de texto, puedes añadir el cuerpo JSON.

Actualmente, este cuerpo JSON contiene solo una propiedad para el título (title) de la entrada.

Envía la solicitud haciendo clic en el botón Send. Si todo va bien, el servidor devolverá un estado 201 - Created con el objeto entrada recién creado como respuesta.

El estado predeterminado de esta recién creada entrada es borrador (draft). Podemos actualizar el estado (status), así como algunas otras propiedades, enviando otra solicitud POST, PUT o PATCH. En mi caso, el ID de la entrada devuelta es 232, por lo que enviaré una solicitud al siguiente punto de conexión:

1	$ POST /wp/v2/posts/232

El cuerpo de la solicitud para actualizar el status y la propiedad content tiene el siguiente aspecto:

1	{
2	"status": "publish",
3	"content": "This is the content of the post"
4	}

Después de enviar la solicitud, el servidor devolverá un estado 200 - OK, lo que significa que la entrada ha sido actualizada correctamente.

En el ejemplo anterior, nos encontramos con los tres siguientes argumentos para crear una entrada:

title
status
content

La lista completa de argumentos admitidos para crear una entrada pueden ser recuperados mediante una simple solicitud OPTIONS de la siguiente manera:

1	$ OPTIONS /wp/v2/posts

A continuación, podemos comprobar la propiedad args en la matriz de métodos POST.

Ahora que hemos aprendido cómo podemos crear y actualizar una entrada, echemos un vistazo a algunos recursos adicionales con los que podemos trabajar.

Crear y actualizar metadatos de entrada

Actualización: Trabajar con metadatos de entrada y de página en la REST API de WP ahora requiere un plugin complementario disponible en GitHub creado por el equipo de la REST API de WP.

El metadato de la entrada se puede crear enviando una solicitud POST a la siguiente ruta:

1	/wp/v2/posts/(?P<parent_id>[\d]+)/meta

Dónde (?P<parent_id>[\d]+) es el ID de la entrada padre. Yo usaré el ID de la entrada que creamos en la sección anterior, que es 232.

De forma similar a cómo enviamos un cuerpo de solicitud para crear un objeto de entrada, es posible enviar un objeto JSON que comprenda dos propiedades para crear un metadato de entrada. Estas dos propiedades son key y value.

1	{
2	"key": "name",
3	"value": "Bilal"
4	}

Los valores de las propiedades key y value son name y Bilal respectivamente.

Envía la solicitud y el servidor devolverá un código de estado 201 - Created, que muestra que el metadato de la entrada ha sido creado correctamente. El objeto de metadato de entrada recién creado también será devuelto en la respuesta:

Ten en cuenta que en el momento de escribir este tutorial, la REST API de WP no admite valores enteros para crear metadatos de entrada. Si intentamos enviar un valor entero en el objeto JSON para crear metadatos de entrada, el servidor devolverá un código de estado 400 - Bad Request.

1	{
2	"key": "value",
3	"value": 12345
4	}

Observa las comillas que faltan alrededor del valor 12345. La respuesta devuelta será como la siguiente:

Por lo tanto, todo lo que envíes acompañando la solicitud para crear metadatos de entrada debe estar en formato de cadena.

Métodos de creación y actualización de datos

Hasta ahora, en este tutorial, hemos estado usando el formato JSON en el cuerpo de la solicitud para crear y actualizar recursos. Echemos un vistazo a todas las opciones que proporciona la REST API de WP para crear y actualizar datos.

Envío de datos como parámetros de URL

La forma más sencilla de enviar datos junto a la solicitud consiste en enviarlos como parámetros de URL. Considera la siguiente solicitud POST para crear una entrada:

1	$ POST /wp/v2/posts?title=the+title&content=this+is+the+content

La solicitud anterior envía dos parámetros al servidor para el título (title) y el contenido (content) de la entrada.

Del mismo modo, para crear metadatos de entrada para una entrada con un ID de 232, usamos la siguiente solicitud POST:

1	$ POST /wp/v2/posts/232/meta?key=name&value=Bilal

La anterior solicitud creará el siguiente objeto meta:

Este método es más adecuado cuando los parámetros son cadenas cortas, como en el ejemplo anterior. Pero a medida que aumenta el número de parámetros y la longitud de sus valores, se complica su administración como parámetros de URL.

Envío de datos como un objeto JSON

Con este método, tomamos argumentos como un par clave/valor en un objeto JSON para pasarlos junto con la solicitud. Hasta ahora, hemos estado usando Postman para enviar solicitudes al servidor. Ahora echaremos un vistazo a cómo podemos implementar este método mediante HTML y jQuery.

Considera el siguiente sencillo formulario que consta de tres campos para title, status y content:

<form name="post-form" id="post-form">
    <label for="title">Title</label>
    <input type="text" name="title" id="title">
    
    <label for="status">Status</label>
    <select name="status" id="status">
    	<option value="publish">Publish</option>
    	<option value="draft">Draft</option>
    </select>
    
    <label for="content">Content</label>
    <textarea name="content" id="content"></textarea>
    
    <input type="submit" name="submit" value="Submit">
</form>

Cuando se envía el anterior formulario, se ejecuta el siguiente código JavaScript (jQuery):

var postForm = $( '#post-form' );

var jsonData = function( form ) {
    var arrData = form.serializeArray(),
        objData = {};
    
    $.each( arrData, function( index, elem ) {
        objData[elem.name] = elem.value;
    });
    
    return JSON.stringify( objData );
};

postForm.on( 'submit', function( e ) {
    e.preventDefault();
    
    $.ajax({
        url: 'https://your-dev-server/wp-json/wp/v2/posts',
        method: 'POST',
        data: jsonData( postForm ),
        crossDomain: true,
        contentType: 'application/json',
        beforeSend: function ( xhr ) {
            xhr.setRequestHeader( 'Authorization', 'Basic username:password' );
        },
        success: function( data ) {
            console.log( data );
        },
        error: function( error ) {
            console.log( error );
        }
    });
});

Al enviar el anterior formulario, enviamos una solicitud AJAX a la ruta /wp/v2/posts. El método jsonData() acepta una instancia jQuery del formulario HTML y convierte sus datos en formato JSON. Estos datos JSON se utilizan en la propiedad data del método $.ajax(). Además, establecemos el tipo de contenido en application/json mediante la propiedad contentType.

Antes de enviar la solicitud, establecemos que la cabecera incluya el header Authorization para usar el método de autenticación básico. Ya hemos aprendido a configurar y utilizar el método básico de autenticación en la segunda parte de esta serie.

Por último, la solicitud se envía a la ruta /wp/v2/posts y una nueva entrada es creada. El servidor devuelve este objeto entrada recién creado como respuesta y simplemente lo registramos en la consola dentro del método success().

En el ejemplo anterior se muestra el uso del formato JSON para enviar datos junto con la solicitud. El origen de este objeto JSON puede ser cualquier cosa además de un formulario HTML, dependiendo de la arquitectura de la aplicación.

Ten en cuenta que para que el anterior código funcione correctamente, es posible que tengas que establecer el campo del header Access-Control-Allow-Headers de forma que incluya los valores Authorization y Content-Type. Esto se puede hacer añadiendo el siguiente código en el archivo .htaccess de tu WordPress:

1	Header set Access-Control-Allow-Headers "Content-Type, Authorization"

Ahora echemos un vistazo al envío de datos a través de formularios HTML.

Envío de datos mediante formularios

La última forma de enviar datos junto a la solicitud es mediante formularios HTML. Estos formularios deben contener campos con el atributo name. El atributo name sirve como un nombre de argumento como por ejemplo title, status, content, etc. Los valores de estos campos sirven a modo de valor para estos argumentos.

Podemos usar el mismo formulario HTML creado en el ejemplo anterior y, a continuación, hacer uso del siguiente código para crear una nueva entrada:

var postForm = $( '#post-form' );

postForm.on( 'submit', function( e ) {
    e.preventDefault();
    
    $.ajax({
        url: 'http://your-dev-server/wp-json/wp/v2/posts',
        method: 'POST',
        data: postForm.serialize(),
        crossDomain: true,
        beforeSend: function ( xhr ) {
            xhr.setRequestHeader( 'Authorization', 'Basic username:password' );
        },
        success: function( data ) {
            console.log( data );
        }
    });
});

El código de arriba es el mismo que el del ejemplo anterior, excepto que eliminamos el método jsonData() y ahora estamos enviando los datos del formulario en formato de cadena utilizando el método serialize() de jQuery. El código jQuery anterior utiliza el tipo de contenido predeterminado application/x-www-form-urlencoded que envía los datos en forma de una cadena gigante con argumentos separados por el signo & y sus valores que son asignados mediante el signo =. Esto es algo similar al envío de datos como parámetros de dirección URL, a excepción de que no expone datos. Esta es una forma eficaz de enviar datos en caso de que estos solo contengan caracteres alfanuméricos.

Para enviar datos binarios (no alfanuméricos), usamos el tipo de contenido multipart/form-data. Este método se puede utilizar si necesitamos cargar imágenes u otros archivos mediante la REST API de WP.

Para enviar datos de formulario en Postman, puedes cambiar a la pestaña Body y, a continuación, utilizar la opción form-data o x-www-form-urlencoded.

Los argumentos se pueden definir en pares clave/valor para enviarlos junto con la solicitud.

Puedes encontrar información detallada sobre los diferentes tipos de formulario en las especificaciones de W3C.

Cargar medios mediante el tipo de contenido `multipart/form-data`

Ahora que hemos examinado el tipo de formulario x-www-form-urlencoded, que envía datos en forma de cadena, comencemos a explorar un tipo de codificación de formulario más avanzado, es decir, multipart/form-data

El tipo de contenido multipart/form-data se utiliza cuando tratamos con datos binarios y, por lo tanto, se puede utilizar para cargar imágenes u otros tipos de archivo en el servidor.

En el ejemplo siguiente, usamos un formulario HTML simple que consta de un input[type="file"] y un poco de jQuery para cargar imágenes en el servidor mediante la ruta /wp/v2/media.

Considera el siguiente formulario HTML:

<form name="image-form" id="image-form">
    <label for="image-input">File</label>
    <input name="image-input" id="image-input" type="file">
    
    <input type="submit" value="Upload">
</form>

El siguiente JavaScript se ejecutará cuando se envíe el anterior formulario:

var imageForm = $( '#image-form' ),
    fileInput = $('#file'),
    formData = new FormData();

imageForm.on( 'submit', function( e ) {
    e.preventDefault();
    
    formData.append( 'file', fileInput[0].files[0] );
    
    $.ajax({
        url: 'http://your-dev-server/wp-json/wp/v2/media',
        method: 'POST',
        data: formData,
        crossDomain: true,
        contentType: false,
        processData: false,
        beforeSend: function ( xhr ) {
            xhr.setRequestHeader( 'Authorization', 'Basic username:password' );
        },
        success: function( data ) {
            console.log( data );
        },
        error: function( error ) {
            console.log( error );
        }
    });
});

Aquí primero obtenemos una instancia de jQuery del formulario y su campo de entrada. A continuación, inicializamos un nuevo objeto FormData. La interfaz FormData proporciona una manera de construir un conjunto de campos de formulario con pares clave/valor y utiliza el mismo formato que el tipo de codificación de formulario multipart/form-data.

Cuando se envía el formulario, evitamos su envío llamando al método .preventDefault() en el objeto de evento. A continuación, anexamos un nuevo campo a la instancia formData mediante el método .append(). El método .append() acepta dos argumentos para el nombre (name) y el valor (value) del campo. La REST API de WP aplica el atributo name del campo de entrada de archivo para que sea file. Es por eso que establecemos el primer argumento, name, de modo que sea file, y para el segundo argumento pasamos un objeto de blob de archivos haciendo referencia al elemento de entrada.

De forma predeterminada, los datos pasados a la propiedad data del método jQuery.ajax() se procesan en una cadena de consulta. Dado que aquí estamos cargando archivos de imagen, no queremos que eso suceda, y por ello, establecemos la propiedad processData en false. También establecemos la propiedad contentType en false para evitar que application/x-www-form-urlencoded se envíe como el tipo de contenido predeterminado al servidor.

Y por último, establecemos el header Authorization para autenticarnos como usuarios con privilegios edit_posts.

Asegúrate de ejecutar el anterior script desde un servidor. Si todo va bien y se carga el archivo, el servidor devolverá el objeto multimedia recién creado.

Esta imagen puede ser configurada después como una imagen destacada para una entrada.

Después de haber examinado detenidamente las formas de crear y actualizar recursos mediante la REST API de WP, veamos cómo podemos eliminarlos.

Eliminar datos con la REST API de WP

Eliminar datos con la REST API de WP es tan sencillo como enviar una solicitud DELETE a un recurso determinado.

Si necesitamos eliminar una entrada con un ID de 10, enviamos la siguiente solicitud DELETE:

1	$ DELETE /wp/v2/posts/10

Esto moverá la entrada a la papelera, pero no la eliminará permanentemente. Para eliminar permanentemente una entrada, usamos el argumento force:

1	$ DELETE /wp/v2/posts/10?force=true

Ten en cuenta que el argumento force es necesario cuando se elimina un recurso que no admite la eliminación de residuos. Ejemplos de estos recursos son los metadatos de entrada y los medios.

Dicho esto, ahora concluimos esta parte de la serie.

¿Qué viene a continuación?

En este largo tutorial, analizamos la creación, actualización y eliminación de diferentes tipos de recursos mediante la REST API de WP. Aprendimos diferentes formas de enviar datos junto a la solicitud, incluido el envío de datos como parámetros de URL, en formato JSON y mediante formularios. Al final del tutorial, aprendimos a eliminar recursos mediante el envío de una solicitud DELETE.

En la próxima y última entrega de la serie, aprenderemos sobre la estructura interna de la REST API de WP y sus clases. También aprenderemos a ampliar la API para modificar las respuestas del servidor. Nos vemos en la siguiente parte de la serie, mantente atento...