Cosa devi sapere sulla nuova API REST di WordPress

WordPress 4.4 ha reso l'API REST di WordPress una parte del core.

In questo articolo spiegherò perché questo sviluppo è enorme per WordPress (e per gli autori di temi e plugin in generale) e ti mostrerò come usarlo per semplificare il processo di comunicazione tra WordPress e altre app.

L'API Rest di WordPress consente inoltre ai siti Web di WordPress di sbarazzarsi dell'interfaccia di amministrazione di WordPress predefinita per offrire un'esperienza di amministrazione o contenuto completamente personalizzata utilizzando uno stack tecnologico diversificato.

Calypso, l'app desktop di WordPress, ne è un bellissimo esempio. Calypso è costruito utilizzando un'unica applicazione Javascript che utilizza l'API REST di WordPress per comunicare tra WordPress.com e il core.

Poiché l'API REST di WordPress è ora parte integrante del core di WordPress, è importante che gli sviluppatori acquisiscano una buona conoscenza di come funziona e delle nuove possibilità che offre per interagire con WordPress.

E quindi in questa panoramica e tutorial sull'API REST di WordPress, ti guiderò attraverso le basi dell'API REST di WP e ti mostrerò come utilizzarla per creare un widget (plugin) che mostra gli ultimi post di Heroic Knowledge Tipi di post personalizzati di base.

Un primer sull'API REST di WordPress

Prima di vedere come utilizzare l'API REST di WordPress per creare un widget (plugin), prima capiamo meglio il termine.

Quindi cosa significa API?

API sta per Application Program Interface .

In parole povere, è un mezzo di comunicazione tra due diverse applicazioni.

Un esempio comune di API in azione è il Tweet Deck visualizzato da molti siti web. La visualizzazione di questo Tweet Deck diventa possibile tramite un'API in cui il sito Web estrae semplicemente i dati da Twitter e li visualizza.

E il RIPOSO?

REST è l'abbreviazione di REpresentational State Transfer .

REST è uno stile architettonico basato su HTML per la creazione di API. Un'architettura RESTful utilizza le richieste HTTP per inviare, leggere, aggiornare ed eliminare i dati tra due origini.

Quindi, quando parliamo di API REST, intendiamo essenzialmente un'API che utilizza metodi HTML per comunicare.

E per quanto riguarda JSON?

L'API REST di WordPress è lo stesso formato dell'API REST JSON di WordPress.

JSON (o Javascript Object Notation ) è un formato di interscambio dati minimo basato su testo utilizzato per scambiare dati senza interruzioni tra piattaforme diverse (anche se le piattaforme utilizzano linguaggi diversi).

JSON è un'alternativa leggera alle soluzioni basate su XML, il che lo rende perfetto per le app mobili con limitazioni di larghezza di banda.

Perché usare l'API REST di WordPress

Potresti chiederti cosa c'è di così eccezionale nell'API REST di WordPress e perché dovresti preoccupartene.

Bene... l'API REST di WordPress ti consente di fare di più con WordPress.

Per esempio:

1. Scrivi applicazioni in qualsiasi lingua che conosci e fallo interagire con un sito WordPress (gli unici 2 requisiti sono che la lingua della tua app deve utilizzare metodi HTML ed essere in grado di interpretare JSON)
2. Progetta esperienze di amministrazione e contenuti completamente personalizzate
3. Sviluppa applicazioni a pagina singola su WordPress

E altro ancora.

È quasi impossibile elencare tutte le potenziali applicazioni/interfacce/esperienze che possono essere create con l'API REST. Il manuale dell'API REST di WordPress dice giustamente:

La nostra immaginazione è l'unico limite a ciò che si può fare con l'API REST di WordPress. La conclusione è che, se desideri un modo strutturato, estensibile e semplice per ottenere dati dentro e fuori WordPress su HTTP, probabilmente vorrai utilizzare l'API REST.

Ma so che l'implementazione è sempre molto più difficile della comprensione della teoria.

Vediamo quindi un breve tutorial su come utilizzare l'API REST di WordPress per creare un widget (plugin) personalizzato.

Un breve tutorial su come utilizzare l'API REST di WordPress

Se disponi di uno dei nostri prodotti della knowledge base, come il nostro tema del centro assistenza KnowAll o il tuo tema con il plug-in Heroic Knowledge Base, avrai un sito con una knowledge base di articoli di supporto. L'uso di questi prodotti non è necessario per seguire i principi di questo tutorial, tuttavia, tieni presente che dovrai adattare qualsiasi codice alla tua configurazione.

Allora, pronto con la tua configurazione locale?

Grande!

Ora quello che faremo è creare un altro sito Web su un server diverso.

Allora perché stiamo creando questo secondo sito web?

Lo stiamo facendo perché vogliamo implementare l'API REST di WordPress per comunicare con questo secondo sito Web e, come ora saprai, l'API REST di WordPress serve a far sì che le conversazioni avvengano.

Quindi utilizzeremo l'API REST di WordPress per far dialogare i due siti Web e scambiare dati.

E l'obiettivo finale del tutorial è:

Scegli gli ultimi articoli della knowledge base pubblicati dal sito Web del Centro assistenza e visualizzali in un widget nella barra laterale del nuovo sito Web.

Ai fini di questo articolo, il sito Web del Centro assistenza che contiene tutti gli articoli della knowledge base verrà denominato sito Web " locale " e il nuovo sito Web in cui verrà visualizzato il widget sarà il sito Web " esterno ".

A questo punto, presumo che tu abbia 1) il tuo sito Web del Centro assistenza "locale" e 2) un nuovo sito Web "esterno" impostato su un server diverso.

E alla fine del tutorial, avremmo visualizzato correttamente un elenco di articoli della knowledge base dal sito Web "locale" sul nuovo sito Web "esterno" (tramite l'API REST di WordPress) utilizzando un widget personalizzato (plugin).

Con questo, siamo pronti per iniziare:

Passaggio 1: inizia copiando il seguente codice boilerplate in un nuovo file .php e salvalo nella cartella dei plug-in del tuo sito Web "esterno".

Vedi il codice completo per questo tutorial sull'API REST di WordPress qui.

/**
* 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' ); } ); 

Questo codice crea un widget molto semplice che mostrerà un titolo a tua scelta.

Aggiungendo il codice nella parte superiore del modello e salvandolo nella directory dei plugin, lo abbiamo creato come plugin (anziché aggiungere il codice al file delle funzioni del tema).

È una piccola cosa, ma la creazione di un widget come plug-in in questo stile ti consente di accenderlo e spegnerlo e di riutilizzarlo anche in altri temi in seguito, se lo desideri, senza la necessità di copiare e incollare.

Una volta installato e attivato, avrai un nuovo widget nell'area Widget della dashboard:

Passaggio 2: utilizza l'API REST di WordPress per recuperare i recenti articoli della knowledge base

Poiché non vuoi modificare o eliminare nulla in questo sviluppo, ci concentreremo solo sulla funzione widget(). È qui che il contenuto del widget viene inviato al sito Web "esterno".

Per "ottenere" l'elenco dei recenti articoli della knowledge base dal sito Web "locale", ci sono alcune cose che dobbiamo sapere:

• Il percorso di base dell'API (quale API utilizzare sul tuo sito, nel nostro caso l'ultima API WP)
• Il percorso utilizzato (l'API WP ha più percorsi per i diversi set di dati e le operazioni disponibili)
• L'endpoint utilizzato (quale azione deve essere eseguita)
• Parametri (I dati associati alla richiesta)

Il percorso di base dell'API è sempre:

 json/wp/v2/ 

E così il percorso API assoluto diventa:

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

(http://example.com è il tuo sito web "locale")

Il percorso utilizzato è:

 json/wp/v2/posts/ 

Informazioni sugli endpoint: questa route ha in realtà tre endpoint differenziati dai metodi HTTP. Questi endpoint sono:

• OTTENERE
• METTERE
• ELIMINARE

In questo esempio, sceglierai l'endpoint GET in modo da poter recuperare (o "ottenere") un elenco degli ultimi post dal sito Web "locale".

Quindi la tua prima riga di codice che interagisce con l'API REST sarà:

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

Successivamente, è necessario verificare se vengono restituiti errori:

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

Tutto ciò che fa questo codice è controllare quale risposta viene restituita. Se la risposta restituisce alcuni post, non ci sono errori.

L'ultima parte di questa sezione è:

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

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

$response è una stringa codificata JSON con dati Post. Quindi tutto ciò che stai facendo qui è decodificarlo in modo che possa essere emesso.

Ancora una volta, aggiungi un ulteriore controllo per assicurarti che $posts non sia vuoto. Se lo è, non viene restituito nulla.

Quindi, a questo punto, hai comunicato con successo con il tuo sito Web "locale" utilizzando l'API. Questa implementazione ti lascia con un elenco di post da visualizzare.

La fase successiva è visualizzarli effettivamente nel tuo widget sul sito Web "esterno".

Passaggio 3: visualizza gli ultimi post sul sito Web "esterno" aggiungendo il seguente codice:

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

Il codice per il tuo widget completato dovrebbe assomigliare a questo:

/**
* 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' ); } ); 

Al termine del passaggio precedente, quando ora provi a visualizzare il tuo sito Web "esterno", vedrai un elenco dei tuoi post dal sito Web "locale" nella barra laterale.

Tutto questo è fantastico.

Tuttavia, se ricordi, questi non sono i post giusti perché vogliamo solo mostrare gli ultimi articoli della Knowledge Base.

La nostra attuale implementazione non lo fa perché il plug-in della Knowledge Base utilizza il proprio tipo di post personalizzato. E poiché i tipi di post personalizzati non sono pubblicamente disponibili per le API per impostazione predefinita, ciò causa un problema. (Nota: l'ultima versione della knowledge base è disponibile pubblicamente per l'API REST e la sezione successiva può essere ignorata)

Utilizzo dell'API REST con tipi di post personalizzati

Per rendere disponibili i tipi di post personalizzati per l'API REST, è necessaria una piccola soluzione alternativa.

Quindi, quando crei un tipo di post personalizzato, devi aggiungere un nuovo parametro al registro del tipo di post args per renderlo pubblicamente disponibile:

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

Ma poiché nel nostro caso utilizziamo un plug-in per alimentare il tipo di post dell'articolo della knowledge base, non modificheremo direttamente il file del plug-in per rendere i tipi di post personalizzati disponibili per l'API REST. (Modificare direttamente un file plug-in non è mai una buona idea!)

Quello che faremo invece è aggiungere il seguente codice al file functions.php nel tema figlio per il sito Web "locale":

/**
* 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';
    }
}

Ora, il tipo di post personalizzato "ht_kb" è pubblicamente disponibile per l'API REST di WP.

Dopo aver reso disponibile il tipo di post personalizzato per l'API REST di WordPress, ora dobbiamo correggere il nostro widget per mostrare i post con quel tipo di post. Per questo, torneremo al codice di risposta $ dal passaggio n. 2 e lo aggiorneremo in:

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

In pratica stiamo cambiando /posts/ in /ht_kb/ nel percorso API perché 'ht_kb' è il nome del tipo di post personalizzato del plugin.

Dopo aver aggiornato il widget e aver visualizzato in anteprima il sito Web "esterno", ora dovresti vedere gli ultimi articoli della Knowledge Base.

Pensieri finali

Come abbiamo visto, usando pochi semplici frammenti di PHP e HTML, puoi creare nuove funzioni, widget e plugin.

È possibile modificare il plug-in che abbiamo appena creato per creare una casella di ricerca che utilizza l'API REST di WP per cercare gli articoli della Knowledge Base e restituire i risultati nel widget.

Oppure puoi usare l'autenticazione per controllare chi vede i risultati (utile se hai creato contenuti con restrizioni).

C'è così tanto che puoi provare! Basta avere le basi giuste e sarai pronto.

Ulteriori letture

Ci sono molti contenuti obsoleti attorno all'API REST di WordPress, quindi assicurati di leggere solo le cose aggiornate. Ho collegato alcune risorse utili durante tutto il post, ma ne sto elencando alcune anche qui.

Quindi leggili e scopri i diversi modi creativi in ​​cui puoi utilizzare l'API REST.

• Manuale dell'API REST
• Domande frequenti sull'API REST
• WP REST API: è qui che siamo diretti?

Se hai domande sull'implementazione dell'API REST di WordPress, rilasciale nei commenti qui sotto!