Ce trebuie să știți despre noul WordPress REST API

WordPress 4.4 a făcut din API-ul REST WordPress o parte a nucleului.

În acest articol, voi explica de ce această dezvoltare este uriașă pentru WordPress (și pentru autorii de teme și pluginuri în general) și vă voi arăta cum să o utilizați pentru a simplifica procesul de comunicare între WordPress și alte aplicații.

De asemenea, WordPress Rest API face posibil ca site-urile web WordPress să scape de interfața implicită de administrare WordPress pentru a oferi un administrator complet personalizat sau experiențe de conținut folosind o stivă tehnologică diversă.

Calypso – aplicația desktop WordPress – este un exemplu frumos în acest sens. Calypso este construit folosind o singură aplicație Javascript care utilizează WordPress REST API pentru a comunica între WordPress.com și nucleu.

Deoarece WordPress REST API este acum o parte integrantă a nucleului WordPress, este important ca dezvoltatorii să înțeleagă bine cum funcționează și noile posibilități pe care le deschide pentru a interacționa cu WordPress.

Așadar, în această prezentare și tutorial WordPress REST API, vă voi prezenta elementele de bază ale API-ului WP REST și vă voi arăta cum îl puteți utiliza pentru a crea un widget (plugin) care afișează cele mai recente postări din Heroic Knowledge. Tipuri de postări personalizate de bază.

Un prim despre API-ul REST WordPress

Înainte de a vedea cum să folosim API-ul REST WordPress pentru a crea un widget (plugin), să înțelegem mai întâi termenul puțin mai bine.

Deci, ce înseamnă API?

API înseamnă Application Program Interface .

În termeni cei mai simpli, este un mijloc de comunicare între două aplicații diferite.

Un exemplu comun de API în acțiune este Tweet Deck-ul pe care îl afișează multe site-uri web. Afișarea acestui Tweet Deck devine posibilă printr-un API în care site-ul web doar extrage date de pe Twitter și le afișează.

Dar REST?

REST este prescurtarea pentru REpresentational State Transfer .

REST este un stil arhitectural bazat pe HTML de construire a API-urilor. O arhitectură RESTful folosește cereri HTTP pentru a posta, citi, actualiza și șterge date între două surse.

Deci, când vorbim de un API REST, ne referim în esență la un API care utilizează metode HTML pentru a comunica.

Și ce zici de JSON?

API-ul REST WordPress are același format ca API-ul REST JSON WordPress.

JSON (sau Javascript Object Notation ) este un format de schimb de date minim, bazat pe text, care este folosit pentru a face schimb de date fără probleme între diferite platforme (chiar dacă platformele folosesc limbi diferite).

JSON este o alternativă ușoară la soluțiile bazate pe XML, făcându-l perfect pentru aplicațiile mobile cu limitări de lățime de bandă.

De ce să folosiți API-ul REST WordPress

S-ar putea să vă întrebați ce este atât de excepțional la API-ul REST WordPress și de ce ar trebui să vă pese de el.

Ei bine... API-ul REST WordPress vă permite să faceți mai multe cu WordPress.

De exemplu:

1. Scrieți aplicații în orice limbă pe care o cunoașteți și faceți-l să interacționeze cu un site WordPress (singurele 2 cerințe fiind ca limba aplicației dvs. să folosească metode HTML și să poată interpreta JSON)
2. Proiectați experiențe de administrare și conținut complet personalizate
3. Dezvoltați aplicații cu o singură pagină pe WordPress

Și mult mai mult.

Este aproape imposibil să enumerați toate aplicațiile/interfețele/experiențele potențiale care pot fi create cu API-ul REST. Manualul WordPress REST API spune pe bună dreptate:

Imaginația noastră este singura limită a ceea ce se poate face cu API-ul REST WordPress. Concluzia este că, dacă doriți o modalitate structurată, extensibilă și simplă de a introduce și ieși date din WordPress prin HTTP, probabil că doriți să utilizați API-ul REST.

Dar știu că implementarea este întotdeauna mult mai dificilă decât înțelegerea teoriei.

Deci, haideți să vedem un tutorial rapid despre cum puteți utiliza API-ul REST WordPress pentru a crea un widget personalizat (plugin).

Un tutorial rapid despre cum să utilizați API-ul REST WordPress

Dacă aveți unul dintre produsele noastre din baza de cunoștințe, cum ar fi tema Centrului de ajutor KnowAll sau propria temă cu pluginul Heroic Knowledge Base, veți avea un site cu o bază de cunoștințe de articole de asistență. Utilizarea acestor produse nu este necesară pentru a urma principiile acestui tutorial, totuși, rețineți că va trebui să adaptați orice cod la configurația dvs.

Deci, gata cu configurația locală?

Grozav!

Acum ceea ce vom face este să creăm un alt site web pe un alt server.

Deci, de ce creăm acest al doilea site web?

Facem acest lucru pentru că dorim să implementăm API-ul REST WordPress pentru a comunica cu acest al doilea site web și, după cum știți acum, API-ul REST WordPress este totul despre a face conversațiile să aibă loc.

Așa că vom folosi API-ul WordPress REST pentru a face ca cele două site-uri web să vorbească între ele și să facă schimb de date.

Și scopul final al tutorialului este:

Alegeți cele mai recente articole publicate din baza de cunoștințe de pe site-ul web al centrului de ajutor și afișați-le într-un widget în bara laterală a noului site web.

De dragul acestui articol, site-ul web al centrului de ajutor care conține toate articolele din baza de cunoștințe va fi denumit site-ul „ local ”, iar noul site web pe care veți afișa widget-ul va fi site-ul „ extern ”.

În acest moment, presupun că aveți 1) site-ul web „local” al centrului de ajutor și 2) un nou site web „extern” configurat pe un alt server.

Și la sfârșitul tutorialului, am fi afișat cu succes o listă de articole din baza de cunoștințe de pe site-ul „local” pe noul site „extern” (prin intermediul API-ului WordPress REST) ​​folosind un widget personalizat (plugin).

Cu asta, suntem gata să începem:

Pasul #1: Începeți prin a copia următorul cod standard într-un nou fișier .php și salvați-l în folderul de pluginuri de pe site-ul dvs. „extern”.

Consultați codul complet pentru acest tutorial WordPress REST API aici.

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

Acest cod creează un widget foarte simplu care va afișa un titlu pe care îl alegeți.

Adăugând codul în partea de sus a șablonului și salvându-l în directorul de pluginuri, l-am creat ca plugin (în loc să adăugăm codul în fișierul de funcții al temei).

Este un lucru mic, dar crearea unui widget ca plugin în acest stil vă permite să îl puteți porni și dezactiva și, de asemenea, să îl reutilizați în alte teme mai târziu, dacă doriți, fără a fi nevoie să copiați și să lipiți.

Odată instalat și activat, veți avea un nou widget în zona Widgeturi a tabloului de bord:

Pasul #2: Utilizați API-ul REST WordPress pentru a prelua articolele recente din baza de cunoștințe

Pentru că nu doriți să editați sau să ștergeți nimic în această dezvoltare, ne vom concentra doar pe funcția widget(). Acesta este locul în care conținutul din widget este trimis către site-ul web „extern”.

Pentru a „obține” lista articolelor recente din baza de cunoștințe de pe site-ul „local”, există câteva lucruri pe care trebuie să le știm:

• Calea de bază a API-ului (ce API să utilizați pe site-ul dvs., în cazul nostru cel mai recent API WP)
• Ruta utilizată (WP API are mai multe rute pentru diferitele seturi de date și operațiuni disponibile)
• Punctul final utilizat (Ce acțiune trebuie efectuată)
• Parametri (datele asociate cu cererea)

Calea de bază a API-ului este întotdeauna:

 json/wp/v2/ 

Și astfel calea API absolută devine:

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

(http://example.com este site-ul dvs. „local”)

Traseul folosit este:

 json/wp/v2/posts/ 

Despre punctele finale: această rută are de fapt trei puncte finale care sunt diferențiate prin metodele HTTP. Aceste puncte finale sunt:

• OBȚINE
• A PUNE
• ȘTERGE

În acest exemplu, veți alege punctul final GET, astfel încât să puteți prelua (sau „obține”) o listă cu cele mai recente postări de pe site-ul „local”.

Prin urmare, prima linie de cod care interacționează cu API-ul REST va fi:

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

În continuare, trebuie să verificați dacă sunt returnate erori:

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

Tot ceea ce face acest cod este să verifice ce răspuns este returnat. Dacă răspunsul returnează unele postări, atunci nu există nicio eroare.

Ultima parte a acestei secțiuni este:

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

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

$response este un șir codificat JSON cu date Post. Deci tot ceea ce faci aici este să-l decodazi astfel încât să poată fi scos.

Din nou, adăugați o verificare suplimentară pentru a vă asigura că $posts nu este gol. Dacă este, atunci nu se returnează nimic.

Deci, în acest moment, ați comunicat cu succes cu site-ul dvs. „local” folosind API-ul. Această implementare vă lasă cu o listă de postări de afișat.

Următoarea etapă este să le afișați efectiv în widget-ul dvs. pe site-ul „extern”.

Pasul #3: Afișați cele mai recente postări pe site-ul „extern” adăugând următorul cod:

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

Codul pentru widget-ul completat ar trebui să arate astfel:

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

După finalizarea pasului de mai sus, când încercați să vizualizați site-ul dvs. „extern”, veți vedea o listă a postărilor dvs. de pe site-ul „local” în bara laterală.

Toate acestea sunt grozave.

Cu toate acestea, dacă vă amintiți, acestea nu sunt postările potrivite, deoarece vrem să arătăm doar cele mai recente articole din Baza de cunoștințe.

Implementarea noastră actuală nu face acest lucru, deoarece pluginul Knowledge Base folosește propriul tip de postare personalizat. Și deoarece tipurile de postări personalizate nu sunt disponibile public pentru API-uri în mod implicit, acest lucru cauzează o problemă. (Notă: cea mai recentă versiune a bazei de cunoștințe este disponibilă public pentru API-ul REST și următoarea secțiune poate fi omisă)

Utilizarea API-ului REST cu tipuri de postări personalizate

Pentru a face tipuri de postări personalizate disponibile pentru API-ul REST, aveți nevoie de o mică soluție.

Deci, atunci când creați un tip de postare personalizat, trebuie să adăugați un nou parametru în registrul argumentelor tipului de postare pentru a-l face disponibil public:

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

Dar pentru că în cazul nostru, folosim un plugin pentru a alimenta tipul de postare a articolului din baza de cunoștințe, nu vom edita direct fișierul plugin pentru a face tipurile de postări personalizate disponibile pentru API-ul REST. (Editarea directă a unui fișier plugin nu este niciodată o idee bună!)

Ceea ce vom face în schimb este să adăugăm următorul cod la fișierul functions.php în tema copil pentru site-ul „local”:

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

Acum, tipul de postare personalizat „ht_kb” este disponibil public pentru API-ul WP REST.

După ce am pus la dispoziție tipul de postare personalizat pentru API-ul REST WordPress, acum trebuie să reparăm widgetul nostru pentru a afișa postările cu acel tip de postare. Pentru asta, vom reveni la codul $response de la Pasul #2 și îl vom actualiza la:

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

Practic, schimbăm /posturile/ în /ht_kb/ în ruta API, deoarece „ht_kb” este numele tipului de postare personalizat al pluginului.

Odată ce actualizați widgetul și previzualizați site-ul „extern”, ar trebui să vedeți acum cele mai recente articole din Baza de cunoștințe.

Gânduri finale

Ei bine, după cum am văzut, folosind câteva fragmente simple de PHP și HTML, puteți crea noi funcții, widget-uri și plugin-uri.

Puteți modifica pluginul pe care tocmai l-am creat pentru a crea o casetă de căutare care utilizează API-ul WP REST pentru a căuta articolele din baza de cunoștințe și pentru a returna rezultatele în widget.

Sau, puteți folosi autentificarea pentru a controla cine vede rezultatele (util dacă ați creat conținut restricționat).

Sunt atât de multe pe care le poți încerca! Doar obțineți corect elementele de bază și veți fi gata.

Lectură în continuare

Există o mulțime de conținut învechit în jurul API-ului WordPress REST, așa că asigurați-vă că citiți doar lucrurile actualizate. Am creat linkuri către câteva resurse utile pe tot parcursul postării, dar am enumerat câteva și aici.

Așa că citiți mai multe despre ele și aflați diferitele moduri creative prin care puteți utiliza API-ul REST.

• Manual API REST
• Întrebări frecvente despre API-ul REST
• WP REST API: aici ne îndreptăm?

Dacă aveți întrebări despre implementarea API-ului REST WordPress, trimiteți-le în comentariile de mai jos!