Lo que necesita saber sobre la nueva API REST de WordPress

Publicado: 2018-01-25

WordPress 4.4 hizo que la API REST de WordPress fuera parte del núcleo.

En este artículo, explicaré por qué este desarrollo es enorme para WordPress (y los autores de temas y complementos en general) y le mostraré cómo usarlo para simplificar el proceso de comunicación entre WordPress y otras aplicaciones.

La API Rest de WordPress también hace posible que los sitios web de WordPress se deshagan de la interfaz de administración predeterminada de WordPress para ofrecer experiencias de administración o contenido completamente personalizadas utilizando una pila de tecnología diversa.

Calypso, la aplicación de escritorio de WordPress, es un hermoso ejemplo de esto. Calypso está construido usando una sola aplicación Javascript que usa la API REST de WordPress para comunicarse entre WordPress.com y el núcleo.

Debido a que la API REST de WordPress ahora es una parte integral del núcleo de WordPress, es importante que los desarrolladores entiendan bien cómo funciona y las nuevas posibilidades que abre para interactuar con WordPress.

Y así, en esta descripción general y tutorial de la API REST de WordPress, lo guiaré a través de los conceptos básicos de la API REST de WP y le mostraré cómo puede usarlo para crear un widget (complemento) que muestre las últimas publicaciones de Heroic Knowledge. Tipos básicos de publicaciones personalizadas.

Introducción a la API REST de WordPress

Antes de ver cómo usar la API REST de WordPress para crear un widget (complemento), primero comprendamos un poco mejor el término.

Entonces, ¿qué significa API?

API significa interfaz de programa de aplicación .

En términos más simples, es un medio de comunicación entre dos aplicaciones diferentes.

Un ejemplo común de una API en acción es el Tweet Deck que muestran muchos sitios web. Mostrar este Tweet Deck es posible a través de una API donde el sitio web simplemente extrae datos de Twitter y los muestra.

¿Qué pasa con el DESCANSO?

REST es la abreviatura de Transferencia de estado representacional .

REST es un estilo arquitectónico basado en HTML para crear API. Una arquitectura RESTful utiliza solicitudes HTTP para publicar, leer, actualizar y eliminar datos entre dos fuentes.

Entonces, cuando hablamos de una API REST, esencialmente nos referimos a una API que usa métodos HTML para comunicarse.

¿Y qué pasa con JSON?

La API REST de WordPress tiene el mismo formato que la API REST JSON de WordPress.

JSON (o notación de objetos Javascript ) es un formato mínimo de intercambio de datos basado en texto que se usa para intercambiar datos sin problemas entre diferentes plataformas (incluso si las plataformas usan diferentes idiomas).

JSON es una alternativa ligera a las soluciones basadas en XML, lo que lo hace perfecto para aplicaciones móviles con limitaciones de ancho de banda.

Por qué usar la API REST de WordPress

Es posible que se pregunte qué tiene de excepcional la API REST de WordPress y por qué debería preocuparse por ella.

Bueno... la API REST de WordPress te permite hacer más con WordPress.

Por ejemplo:

  1. Escriba aplicaciones en cualquier idioma que conozca y haga que interactúe con un sitio de WordPress (los únicos 2 requisitos son que el idioma de su aplicación debe usar métodos HTML y poder interpretar JSON)
  2. Diseñe experiencias de administración y contenido completamente personalizadas
  3. Desarrolle aplicaciones de una sola página sobre WordPress

Y mucho más.

Es casi imposible enumerar todas las aplicaciones/interfaces/experiencias potenciales que se pueden crear con la API REST. El manual de la API REST de WordPress dice correctamente:

Nuestra imaginación es el único límite de lo que se puede hacer con la API REST de WordPress. La conclusión es que, si desea una forma estructurada, extensible y simple de ingresar y sacar datos de WordPress a través de HTTP, probablemente desee usar la API REST.

Pero sé que la implementación siempre es mucho más difícil que comprender la teoría.

Entonces, veamos un tutorial rápido sobre cómo puede usar la API REST de WordPress para crear un widget (complemento) personalizado.

Un tutorial rápido sobre cómo usar la API REST de WordPress

Si tiene uno de nuestros productos de base de conocimiento, como nuestro tema del centro de ayuda KnowAll o su propio tema con el complemento Heroic Knowledge Base, tendrá un sitio con una base de conocimiento de artículos de soporte. No es necesario usar estos productos para seguir los principios de este tutorial; sin embargo, tenga en cuenta que deberá adaptar cualquier código a su propia configuración.

Entonces, ¿estás listo con tu configuración local?

¡Estupendo!

Ahora lo que vamos a hacer es crear otro sitio web en un servidor diferente.

Entonces, ¿por qué estamos creando este segundo sitio web?

Lo hacemos porque queremos implementar la API REST de WordPress para comunicarnos con este segundo sitio web y, como ya saben, la API REST de WordPress tiene que ver con hacer que las conversaciones sucedan.

Así que vamos a usar la API REST de WordPress para que los dos sitios web hablen entre sí e intercambien datos.

Y el objetivo final del tutorial es:

Elija los últimos artículos publicados de la base de conocimientos del sitio web del centro de ayuda y muéstrelos en un widget en la barra lateral del nuevo sitio web.

Por el bien de este artículo, el sitio web del centro de ayuda que tiene todos los artículos de la base de conocimientos se denominará sitio web " local " y el nuevo sitio web en el que se mostrará el widget será el sitio web " externo ".

En este punto, supongo que tiene 1) el sitio web de su centro de ayuda 'local' y 2) un nuevo sitio web 'externo' configurado en un servidor diferente.

Y al final del tutorial, habríamos mostrado con éxito una lista de artículos de la base de conocimiento del sitio web 'local' en el nuevo sitio web 'externo' (a través de la API REST de WordPress) usando un widget personalizado (complemento).

Con eso, estamos listos para comenzar:

Paso #1: Comience copiando el siguiente código repetitivo en un nuevo archivo .php y guárdelo en la carpeta de complementos de su sitio web 'externo'.

Vea el código completo para este tutorial de la API REST de WordPress aquí. 

/**
* HeroThemes Example Widget
*/
class My_Widget extends WP_Widget { 

    //set up widget
    public function __construct() { 

        $widget_ops = array( 
                        'classname' => 'rest-api-test-widget',
                        'description' => 'This example provides a framework for how we will build our widget'
        );

        parent::__construct( 'my_widget', 'My Widget', $widget_ops );
    }


    /**
     * Outputs the content of the widget
     * @param array $args
     * @param array $instance
     */

    public function widget( $args, $instance ) {
        //outputs the content of the widget
        echo $args['before_widget'];

        if( !empty( $instance['title'] ) ) {
          echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'], $instance, $this->id_base ) . $args['after_title'];

        }

        // Main Widget Content Goes Here

        echo $args['after_widget'];
    }


    /**
     * Outputs the options form on admin
     * @param array $instance The widget options
     */

    public function form( $instance ) {
        //outputs the options form on admin
        $title = ( !empty( $instance['title'] ) ) ? $instance['title'] : ''; ?>

        <label for="<?php echo $this->get_field_name( 'title' ); ?>">Title: </label>

        <input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" 
        name="<?php echo $this->get_field_name( 'title' ); ?>" 
        type="text" value="<?php echo esc_attr( $title ); ?>" />
    
        <?php 
    } 

} 

 add_action( 'widgets_init', function(){ register_widget( 'My_Widget' ); } );

Este código crea un widget muy simple que mostrará un título de su elección.

Al agregar el código en la parte superior de la plantilla y guardarlo en el directorio de complementos, lo creamos como un complemento (en lugar de agregar el código al archivo de funciones del tema).

Es algo pequeño, pero crear un widget como complemento en este estilo le permite activarlo y desactivarlo y también reutilizarlo en otros temas más adelante si lo desea, sin la necesidad de copiar y pegar.

Una vez instalado y activado, tendrá un nuevo widget en el área de Widgets del tablero:

widget-admin

Paso n.º 2: use la API REST de WordPress para obtener los artículos recientes de la base de conocimientos

Debido a que no desea editar ni eliminar nada en este desarrollo, solo nos centraremos en la función widget(). Aquí es donde el contenido del widget se envía al sitio web 'externo'.

Para "obtener" la lista de artículos recientes de la base de conocimientos del sitio web "local", hay algunas cosas que debemos saber:

  • La ruta base de la API (qué API usar en su sitio, en nuestro caso, la última API de WP)
  • La ruta utilizada (WP API tiene múltiples rutas para los diferentes conjuntos de datos y operaciones disponibles)
  • El punto final utilizado (Qué acción se va a realizar)
  • Parámetros (Los datos asociados a la solicitud)

La ruta base de la API siempre es:

 json/wp/v2/

Y así, la ruta absoluta de la API se convierte en:

 http://example.com/json/wp/v2/

(http://example.com es su sitio web 'local')

La ruta utilizada es:

 json/wp/v2/posts/

Acerca de los puntos finales: esta ruta en realidad tiene tres puntos finales que se diferencian por los métodos HTTP. Estos puntos finales son:

  • OBTENER
  • PONER
  • ELIMINAR

En este ejemplo, elegirá el punto final GET para poder recuperar (u 'obtener') una lista de las publicaciones más recientes del sitio web 'local'.

Entonces, su primera línea de código que interactúa con la API REST será:

$response = wp_remote_get( 'http://products-website.com/wp-json/wp/v2/posts/' );

A continuación, debe verificar si se devuelve algún error:

if( is_wp_error( $response ) ) {
    return;
}

Todo lo que hace este código es verificar qué respuesta se devuelve. Si la respuesta devuelve algunas publicaciones, entonces no hay error.

La última parte de esta sección es:


$posts = json_decode( wp_remote_retrieve_body( $response ) );

if( empty( $posts ) ) {
   return;
}

$response es una cadena codificada en JSON con datos de publicación. Entonces, todo lo que está haciendo aquí es decodificarlo para que pueda generarse.

Nuevamente, agregue una verificación adicional para asegurarse de que $posts no esté vacío. Si es así, no se devuelve nada.

Entonces, en este punto, se ha comunicado con éxito con su sitio web 'local' utilizando la API. Esta implementación te deja con una lista de publicaciones para mostrar.

La siguiente etapa es mostrarlos en su widget en el sitio web 'externo'.

Paso #3: Muestre las últimas publicaciones en el sitio web 'externo' agregando el siguiente código:

		if( !empty( $posts ) ) {
		
			echo '<ul>';
			foreach( $posts as $post ) {
				echo '<li><a href="' . $post->link. '">' . $post->title->rendered . '</a></li>';
			}
			echo '</ul>';
			
		}

El código para su widget completo debería verse así: 

/**
* HeroThemes REST API Widget
*/
class REST_API_Widget extends WP_Widget { 

	//set up widget 
	public function __construct() { 
		$widget_ops = array( 	'classname' => 'rest-api-widget',
 								'description' => 'A REST API widget that pulls posts from a different website'
 		);
 		parent::__construct( 'rest_api_widget', 'REST API Widget', $widget_ops );
 	}

	/**
	* Outputs the content of the widget
	*
	* @param array $args
	* @param array $instance
	*/
	public function widget( $args, $instance ) {
		//change this url to the WP-API endpoint for your site!
		$response = wp_remote_get( 'https://example.com/wp-json/wp/v2/ht-kb/' );

		if( is_wp_error( $response ) ) {
			return;
		}

		$posts = json_decode( wp_remote_retrieve_body( $response ) );

		if( empty( $posts ) ) {
			return;
		}

		echo $args['before_widget'];
		if( !empty( $instance['title'] ) ) {
			echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'], $instance, $this->id_base ) . $args['after_title'];
		}
		
		//main widget content
		if( !empty( $posts ) ) {
		
			echo '<ul>';
			foreach( $posts as $post ) {
				echo '<li><a href="' . $post->link. '">' . $post->title->rendered . '</a></li>';
			}
			echo '</ul>';
			
		}

		echo $args['after_widget'];
	}

	/**
	* Outputs the options form on admin
	*
	* @param array $instance The widget options
	*/
	public function form( $instance ) {
		// outputs the options form on admin
		$title = ( !empty( $instance['title'] ) ) ? $instance['title'] : '';
		?>

		<label for="<?php echo $this->get_field_name( 'title' ); ?>">Title: </label>
		<input class="widefat" id="<?php echo $this->get_field_id( 'title' ); ?>" 
		  name="<?php echo $this->get_field_name( 'title' ); ?>" 
		  type="text" value="<?php echo esc_attr( $title ); ?>" />
		
		<?php 
	} 

 } 

 add_action( 'widgets_init', function(){ register_widget( 'REST_API_Widget' ); } );

Una vez realizado el paso anterior, cuando intente ver su sitio web 'externo', verá una lista de sus publicaciones del sitio web 'local' en su barra lateral.

artilugio

Todo esto es genial.

Sin embargo, si recuerda, estas no son las publicaciones correctas porque solo queremos mostrar los últimos artículos de la Base de conocimientos.

Nuestra implementación actual no hace esto porque el complemento de la base de conocimiento usa su propio tipo de publicación personalizada. Y debido a que los tipos de publicaciones personalizadas no están disponibles públicamente para las API de forma predeterminada, esto genera un problema. (Nota: la última versión de la base de conocimiento está disponible públicamente para la API REST y se puede omitir la siguiente sección)

Uso de la API REST con tipos de publicaciones personalizadas

Para que los tipos de publicaciones personalizadas estén disponibles para la API REST, necesita una pequeña solución.

Por lo tanto, al crear un tipo de publicación personalizado, debe agregar un nuevo parámetro para registrar los argumentos del tipo de publicación para que esté disponible públicamente:


'show_in_rest' = true,
'rest_base' = 'ht_kb',
'rest_controller_class' = 'WP_REST_Posts_Controller',

Pero debido a que en nuestro caso, estamos usando un complemento para potenciar el tipo de publicación del artículo de la base de conocimiento, no editaremos directamente el archivo del complemento para que los tipos de publicación personalizados estén disponibles para la API REST. (¡Editar un archivo de complemento directamente nunca es una buena idea!)

Lo que haremos en su lugar es agregar el siguiente código al archivo functions.php en el tema secundario para el sitio web 'local':

La última versión de KnowAll y Heroic Knowledge Base ya tienen habilitado el soporte REST, esto se puede deshabilitar con el filtro ht_kb_show_in_rest , pero puede modificar el código a continuación para su propio tipo de publicación personalizada. 
/**
* Add rest support to an existing post type
*/
add_action( 'init', 'my_custom_post_type_rest_support', 25 );

function my_custom_post_type_rest_support() {
    global $wp_post_types;

    //set this to the name of your post type!
    $post_type_name = 'ht_kb';
    if( isset( $wp_post_types[ $post_type_name ] ) ) {
        $wp_post_types[$post_type_name]->show_in_rest = true;
        $wp_post_types[$post_type_name]->rest_base = $post_type_name;
        $wp_post_types[$post_type_name]->rest_controller_class = 'WP_REST_Posts_Controller';
    }
}

Ahora, el tipo de publicación personalizada 'ht_kb' está disponible públicamente para la API REST de WP.

Después de hacer que el tipo de publicación personalizada esté disponible para la API REST de WordPress, ahora debemos arreglar nuestro widget para mostrar publicaciones con ese tipo de publicación. Para eso, volveremos al código de $respuesta del paso n.º 2 y lo actualizaremos a:

$response = wp_remote_get( 'http://example.com/wp-json/wp/v2/ht_kb/' );

Básicamente estamos cambiando /posts/ a /ht_kb/ en la ruta API porque 'ht_kb' es el nombre del tipo de publicación personalizada del complemento.

Una vez que actualice su widget y obtenga una vista previa del sitio web 'externo', ahora debería ver los últimos artículos de la Base de conocimientos.

widget-kb-contenido

Pensamientos finales

Bueno, como hemos visto, usando algunos fragmentos simples de PHP y HTML, puede crear nuevas funciones, widgets y complementos.

Puede modificar el complemento que acabamos de crear para crear un cuadro de búsqueda que use la API REST de WP para buscar los artículos de la base de conocimientos y devolver los resultados en el widget.

O bien, puede utilizar la autenticación para controlar quién ve los resultados (útil si ha creado contenido restringido).

¡Hay tanto que puedes probar! Solo obtenga los conceptos básicos correctos y estará listo.

Otras lecturas

Hay una gran cantidad de contenido obsoleto en la API REST de WordPress, así que asegúrese de leer las actualizaciones. He vinculado a algunos recursos útiles a lo largo de la publicación, pero también enumero algunos aquí.

Lea sobre ellos y descubra las diferentes formas creativas en que puede usar la API REST.

  • Manual de la API REST
  • Preguntas frecuentes sobre la API REST
  • API REST de WP: ¿aquí nos dirigimos?

Si tiene alguna pregunta sobre la implementación de la API REST de WordPress, ¡déjela en los comentarios a continuación!