Was Sie über die neue WordPress-REST-API wissen müssen

Veröffentlicht: 2018-01-25

WordPress 4.4 hat die WordPress REST API zu einem Teil des Kerns gemacht.

In diesem Artikel erkläre ich, warum diese Entwicklung für WordPress (und Theme- und Plugin-Autoren im Allgemeinen) enorm ist, und zeige Ihnen, wie Sie damit den Kommunikationsprozess zwischen WordPress und anderen Apps vereinfachen können.

Die WordPress-Rest-API ermöglicht es WordPress-Websites auch, die standardmäßige WordPress-Admin-Oberfläche loszuwerden, um mithilfe eines vielfältigen Technologie-Stacks ein vollständig personalisiertes Admin- oder Inhaltserlebnis anzubieten.

Calypso – die Desktop-App von WordPress – ist ein schönes Beispiel dafür. Calypso wird mit einer einzigen Javascript-Anwendung erstellt, die die WordPress-REST-API verwendet, um zwischen WordPress.com und dem Kern zu kommunizieren.

Da die WordPress-REST-API jetzt ein integraler Bestandteil des WordPress-Kerns ist, ist es wichtig, dass die Entwickler einen guten Überblick darüber bekommen, wie sie funktioniert und welche neuen Möglichkeiten sie für die Interaktion mit WordPress eröffnet.

Und so werde ich Sie in dieser WordPress-REST-API-Übersicht und diesem Tutorial durch die Grundlagen der WP-REST-API führen und Ihnen zeigen, wie Sie damit ein (Plug-in-)Widget erstellen können, das die neuesten Posts von Heroic Knowledge anzeigt Basis benutzerdefinierter Beitragstypen.

Eine Einführung in die WordPress REST API

Bevor wir sehen, wie man die WordPress-REST-API verwendet, um ein (Plugin-)Widget zu erstellen, wollen wir den Begriff zunächst etwas besser verstehen.

Wofür steht API also?

API steht für Application Program Interface .

Einfach ausgedrückt handelt es sich um ein Kommunikationsmittel zwischen zwei verschiedenen Anwendungen.

Ein gängiges Beispiel für eine API in Aktion ist das Tweet Deck, das auf vielen Websites angezeigt wird. Das Anzeigen dieses Tweet-Decks wird über eine API möglich, bei der die Website einfach Daten von Twitter abruft und anzeigt.

Was ist mit RUHE?

REST ist die Abkürzung für REpresentational State Transfer .

REST ist ein HTML-basierter Architekturstil zum Erstellen von APIs. Eine RESTful-Architektur verwendet HTTP-Anforderungen, um Daten zwischen zwei Quellen zu veröffentlichen, zu lesen, zu aktualisieren und zu löschen.

Wenn wir also von einer REST-API sprechen, meinen wir im Wesentlichen eine API, die HTML-Methoden zur Kommunikation verwendet.

Und was ist mit JSON?

Die WordPress-REST-API hat das gleiche Format wie die WordPress-JSON-REST-API.

JSON (oder Javascript Object Notation ) ist ein minimales, textbasiertes Datenaustauschformat, das zum nahtlosen Austausch von Daten zwischen verschiedenen Plattformen verwendet wird (auch wenn die Plattformen unterschiedliche Sprachen verwenden).

JSON ist eine leichtgewichtige Alternative zu XML-basierten Lösungen, wodurch es sich perfekt für mobile Apps mit Bandbreitenbeschränkungen eignet.

Warum die WordPress-REST-API verwenden?

Sie fragen sich vielleicht, was an der WordPress-REST-API so außergewöhnlich ist und warum Sie sich darum kümmern sollten.

Nun … die WordPress-REST-API ermöglicht es Ihnen, mehr mit WordPress zu tun.

Beispielsweise:

  1. Schreiben Sie Anwendungen in jeder Ihnen bekannten Sprache und lassen Sie sie mit einer WordPress-Site interagieren (die einzigen zwei Anforderungen sind, dass die Sprache Ihrer App HTML-Methoden verwenden und JSON interpretieren kann)
  2. Entwerfen Sie vollständig personalisierte Verwaltungs- und Inhaltserlebnisse
  3. Entwickeln Sie Einzelseitenanwendungen auf Basis von WordPress

Und vieles mehr.

Es ist fast unmöglich, alle potenziellen Anwendungen/Schnittstellen/Erfahrungen aufzulisten, die mit der REST-API erstellt werden können. Das REST-API-Handbuch von WordPress sagt zu Recht:

Unsere Vorstellungskraft ist die einzige Grenze dessen, was mit der WordPress REST API gemacht werden kann. Das Fazit ist, wenn Sie eine strukturierte, erweiterbare und einfache Möglichkeit suchen, Daten über HTTP in und aus WordPress zu bekommen, möchten Sie wahrscheinlich die REST-API verwenden.

Aber ich weiß, dass die Umsetzung immer viel schwieriger ist, als die Theorie zu verstehen.

Sehen wir uns also ein kurzes Tutorial an, wie Sie die WordPress-REST-API verwenden können, um ein benutzerdefiniertes (Plugin-)Widget zu erstellen.

Ein kurzes Tutorial zur Verwendung der WordPress REST API

Wenn Sie eines unserer Wissensdatenbankprodukte haben, wie z. B. unser KnowAll-Hilfezentrumsthema oder Ihr eigenes Thema mit dem Heroic Knowledge Base-Plug-in, haben Sie eine Website mit einer Wissensdatenbank mit Support-Artikeln. Die Verwendung dieser Produkte ist nicht erforderlich, um die Prinzipien dieses Tutorials zu befolgen, aber denken Sie daran, dass Sie jeden Code an Ihr eigenes Setup anpassen müssen.

Also, bereit mit Ihrem lokalen Setup?

Toll!

Jetzt werden wir eine weitere Website auf einem anderen Server erstellen.

Warum erstellen wir also diese zweite Website?

Wir tun dies, weil wir die WordPress-REST-API implementieren möchten, um mit dieser zweiten Website zu kommunizieren, und wie Sie jetzt wissen, dreht sich bei der WordPress-REST-API alles darum, Konversationen zu ermöglichen.

Wir werden also die WordPress-REST-API verwenden, um die beiden Websites dazu zu bringen, miteinander zu kommunizieren und Daten auszutauschen.

Und das Endziel des Tutorials ist:

Wählen Sie die neuesten veröffentlichten Wissensdatenbankartikel von der Hilfecenter-Website aus und zeigen Sie sie in einem Widget in der Seitenleiste der neuen Website an.

Für diesen Artikel wird die Help-Center-Website mit allen Wissensdatenbankartikeln als „ lokale “ Website bezeichnet, und die neue Website, auf der Sie das Widget anzeigen, wird als „ externe “ Website bezeichnet.

An dieser Stelle gehe ich davon aus, dass Sie 1) Ihre „lokale“ Help-Center-Website und 2) eine neue „externe“ Website auf einem anderen Server eingerichtet haben.

Und am Ende des Tutorials hätten wir mithilfe eines benutzerdefinierten (Plugin-)Widgets erfolgreich eine Liste von Wissensdatenbankartikeln von der „lokalen“ Website auf der neuen „externen“ Website (über die WordPress-REST-API) angezeigt.

Damit sind wir startklar:

Schritt Nr. 1: Kopieren Sie zunächst den folgenden Boilerplate-Code in eine neue .php-Datei und speichern Sie ihn im Plugins-Ordner Ihrer „externen“ Website.

Den vollständigen Code für dieses WordPress-REST-API-Tutorial finden Sie hier. 

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

Dieser Code erstellt ein sehr einfaches Widget, das einen Titel Ihrer Wahl anzeigt.

Indem wir den Code oben in der Vorlage hinzugefügt und im Plugins-Verzeichnis gespeichert haben, haben wir es als Plugin erstellt (anstatt den Code zur Funktionsdatei des Themas hinzuzufügen).

Es ist eine kleine Sache, aber wenn Sie ein Widget als Plugin in diesem Stil erstellen, können Sie es ein- und ausschalten und später auch in anderen Themen wiederverwenden, wenn Sie möchten, ohne kopieren und einfügen zu müssen.

Nach der Installation und Aktivierung haben Sie ein neues Widget im Bereich Widgets des Dashboards:

Widget-Admin

Schritt Nr. 2: Verwenden Sie die WordPress-REST-API, um die neuesten Wissensdatenbankartikel abzurufen

Da Sie in dieser Entwicklung nichts bearbeiten oder löschen möchten, konzentrieren wir uns nur auf die Funktion widget(). Hier wird der Inhalt des Widgets an die „externe“ Website ausgegeben.

Um die Liste der neuesten Wissensdatenbankartikel von der „lokalen“ Website zu „erhalten“, müssen wir einige Dinge wissen:

  • Der Basispfad der API (welche API auf Ihrer Website verwendet werden soll, in unserem Fall die neueste WP-API)
  • Die verwendete Route (WP API hat mehrere Routen für die verschiedenen verfügbaren Datensätze und Operationen)
  • Der verwendete Endpunkt (Welche Aktion soll durchgeführt werden)
  • Parameter (Die mit der Anfrage verbundenen Daten)

Der Basispfad der API ist immer:

 json/wp/v2/

Und so wird der absolute API-Pfad zu:

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

(http://example.com ist Ihre „lokale“ Website)

Die verwendete Route ist:

 json/wp/v2/posts/

Zu den Endpunkten: Diese Route hat tatsächlich drei Endpunkte, die durch die HTTP-Methoden unterschieden werden. Diese Endpunkte sind:

  • WERDEN
  • SETZEN
  • LÖSCHEN

In diesem Beispiel wählen Sie den GET-Endpunkt aus, damit Sie eine Liste der neuesten Posts von der „lokalen“ Website abrufen (oder „abrufen“) können.

Ihre erste Codezeile, die mit der REST-API interagiert, lautet also:

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

Als nächstes müssen Sie prüfen, ob Fehler zurückgegeben werden:

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

Dieser Code prüft lediglich, welche Antwort zurückgegeben wird. Wenn die Antwort einige Beiträge zurückgibt, liegt kein Fehler vor.

Der letzte Teil dieses Abschnitts lautet:


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

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

$response ist eine JSON-codierte Zeichenfolge mit Post-Daten. Alles, was Sie hier tun, ist also, es zu decodieren, damit es ausgegeben werden kann.

Fügen Sie erneut eine zusätzliche Überprüfung hinzu, um sicherzustellen, dass $posts nicht leer ist. Wenn dies der Fall ist, wird nichts zurückgegeben.

An diesem Punkt haben Sie also erfolgreich über die API mit Ihrer „lokalen“ Website kommuniziert. Diese Implementierung lässt Sie mit einer Liste von Posts zurück, die angezeigt werden sollen.

Der nächste Schritt besteht darin, sie tatsächlich in Ihrem Widget auf der „externen“ Website anzuzeigen.

Schritt #3: Zeigen Sie die neuesten Beiträge auf der „externen“ Website an, indem Sie den folgenden Code hinzufügen:

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

Der Code für Ihr fertiges Widget sollte folgendermaßen aussehen: 

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

Wenn Sie nach dem obigen Schritt versuchen, Ihre „externe“ Website anzuzeigen, sehen Sie eine Liste Ihrer Posts von der „lokalen“ Website in Ihrer Seitenleiste.

Widget

Das ist alles großartig.

Wenn Sie sich jedoch erinnern, sind dies nicht die richtigen Beiträge, da wir nur die neuesten Artikel aus der Wissensdatenbank anzeigen möchten.

Unsere aktuelle Implementierung tut dies nicht, weil das Knowledge Base-Plugin seinen eigenen benutzerdefinierten Beitragstyp verwendet. Und da benutzerdefinierte Beitragstypen standardmäßig nicht öffentlich für APIs verfügbar sind, verursacht dies ein Problem. (Hinweis: Die neueste Version der Wissensdatenbank ist für die REST-API öffentlich verfügbar und der nächste Abschnitt kann übersprungen werden.)

Verwenden der REST-API mit benutzerdefinierten Beitragstypen

Um benutzerdefinierte Beitragstypen für die REST-API verfügbar zu machen, benötigen Sie eine kleine Problemumgehung.

Wenn Sie also einen benutzerdefinierten Beitragstyp erstellen, müssen Sie einen neuen Parameter zum Register der Beitragstyp-Argumente hinzufügen, um ihn öffentlich verfügbar zu machen:


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

Aber da wir in unserem Fall ein Plug-in verwenden, um den Beitragstyp des Wissensdatenbankartikels zu betreiben, bearbeiten wir die Plug-in-Datei nicht direkt, um die benutzerdefinierten Beitragstypen für die REST-API verfügbar zu machen. (Das direkte Bearbeiten einer Plugin-Datei ist niemals eine gute Idee!)

Stattdessen fügen wir den folgenden Code zur Datei functions.php im Child-Theme für die „lokale“ Website hinzu:

Die neueste Version von KnowAll und Heroic Knowledge Base haben bereits REST-Unterstützung aktiviert, dies kann mit dem ht_kb_show_in_rest -Filter deaktiviert werden, aber Sie können den folgenden Code für Ihren eigenen benutzerdefinierten Beitragstyp ändern. 
/**
* 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';
    }
}

Jetzt ist der benutzerdefinierte Beitragstyp „ht_kb“ öffentlich für die WP REST API verfügbar.

Nachdem wir den benutzerdefinierten Beitragstyp für die WordPress-REST-API verfügbar gemacht haben, müssen wir nun unser Widget so reparieren, dass Beiträge mit diesem Beitragstyp angezeigt werden. Dafür kehren wir zum $response-Code aus Schritt 2 zurück und aktualisieren ihn wie folgt:

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

Wir ändern grundsätzlich /posts/ in /ht_kb/ in der API-Route, da „ht_kb“ der Name des benutzerdefinierten Beitragstyps des Plugins ist.

Nachdem Sie Ihr Widget aktualisiert und eine Vorschau der „externen“ Website angezeigt haben, sollten Sie jetzt die neuesten Artikel aus der Wissensdatenbank sehen.

Widget-KB-Inhalt

Abschließende Gedanken

Wie wir gesehen haben, können Sie mit ein paar einfachen PHP- und HTML-Snippern neue Funktionen, Widgets und Plugins erstellen.

Sie könnten das Plugin, das wir gerade erstellt haben, ändern, um ein Suchfeld zu erstellen, das die WP-REST-API verwendet, um die Knowledge Base-Artikel zu durchsuchen und die Ergebnisse im Widget zurückzugeben.

Oder Sie könnten die Authentifizierung verwenden, um zu steuern, wer die Ergebnisse sieht (nützlich, wenn Sie eingeschränkte Inhalte erstellt haben).

Es gibt so viel, was Sie ausprobieren können! Besorgen Sie sich einfach die Grundlagen, und schon sind Sie fertig.

Weiterlesen

Es gibt eine Menge veralteter Inhalte rund um die WordPress-REST-API, also stellen Sie sicher, dass Sie nur die aktualisierten Inhalte lesen. Ich habe den ganzen Beitrag über auf einige nützliche Ressourcen verlinkt, aber ich liste hier auch einige auf.

Lesen Sie sich diese also durch und finden Sie heraus, auf welche verschiedenen kreativen Arten Sie die REST-API verwenden können.

  • REST-API-Handbuch
  • Häufig gestellte Fragen zur REST-API
  • WP REST API: Wollen wir dahin?

Wenn Sie Fragen zur Implementierung der WordPress-REST-API haben, schreiben Sie sie unten in die Kommentare!