WordPress REST API: Alles, was Sie wissen müssen

WordPress 4.4 machte die WordPress REST API zu einem Teil des Kerns.

In diesem Artikel erkläre ich, warum diese Entwicklung für WordPress (und für Theme- und Plugin-Autoren im Allgemeinen) von großer Bedeutung ist, und zeige Ihnen, wie Sie sie nutzen können, um die Kommunikation zwischen WordPress und anderen Apps zu vereinfachen.

Die WordPress REST API ermöglicht es WordPress-Websites auch, die standardmäßige WordPress-Admin-Oberfläche abzuschaffen, um eine vollständig personalisierte Admin- oder Content-Erfahrung mit einem vielfältigen Technologie-Stack anzubieten.

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

Da die WordPress REST API nun ein integraler Bestandteil des WordPress-Kerns ist, ist es wichtig, dass Entwickler gut verstehen, wie sie funktioniert und welche neuen Möglichkeiten sie für die Interaktion mit WordPress eröffnet.

In dieser Übersicht und diesem Tutorial zur WordPress REST API führe ich Sie durch die Grundlagen der WP REST API und zeige Ihnen, wie Sie damit ein (Plugin-)Widget erstellen können, das die neuesten Beiträge aus den benutzerdefinierten Beitragstypen der Heroic Knowledge Base anzeigt.

Eine Einführung in die WordPress REST API

Bevor wir uns ansehen, wie wir die WordPress REST API zur Erstellung eines (Plugin-)Widgets verwenden, wollen wir den Begriff zunächst besser verstehen.

Was bedeutet also API?

API steht für Application Program Interface (Programmierschnittstelle für Anwendungen).

Vereinfacht ausgedrückt ist es ein Kommunikationsmittel zwischen zwei verschiedenen Anwendungen.

Ein gängiges Beispiel für eine API in Aktion ist die Tweet-Deck-Anzeige, die viele Websites zeigen. Die Anzeige dieses Tweet-Decks wird über eine API ermöglicht, bei der die Website einfach Daten von Twitter abruft und anzeigt.

Was ist mit REST?

REST steht für REpresentational State Transfer.

REST ist ein HTML-basierter Architekturstil für den Aufbau von APIs. Eine RESTful-Architektur verwendet HTTP-Anfragen, um Daten zwischen zwei Quellen zu posten, 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 ist im gleichen 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 leichte Alternative zu XML-basierten Lösungen und somit perfekt für mobile Apps mit Bandbreitenbeschränkungen.

Warum die WordPress REST API verwenden

Sie fragen sich vielleicht, was das Besondere an der WordPress REST API ist und warum Sie sich dafür interessieren sollten.

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

Zum Beispiel:

1. Schreiben Sie Anwendungen in jeder Sprache, die Sie kennen, und lassen Sie sie mit einer WordPress-Site interagieren (die einzigen 2 Voraussetzungen sind, dass die Sprache Ihrer App HTML-Methoden verwenden und JSON interpretieren können muss).
2. Entwerfen Sie vollständig personalisierte Admin- und Content-Erlebnisse
3. Entwickeln Sie Single-Page-Anwendungen auf Basis von WordPress

Und vieles mehr.

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

Unsere Vorstellungskraft ist die einzige Grenze für das, was mit der WordPress REST API gemacht werden kann. Letztendlich, wenn Sie eine strukturierte, erweiterbare und einfache Möglichkeit suchen, Daten über HTTP in und aus WordPress zu erhalten, möchten Sie wahrscheinlich die REST API verwenden.

Aber ich weiß, dass die Implementierung immer viel schwieriger ist als das Verständnis der Theorie.

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 Help Center Theme oder Ihr eigenes Theme mit dem Heroic Knowledge Base Plugin, haben Sie eine Website mit einer Wissensdatenbank aus Support-Artikeln. Die Verwendung dieser Produkte ist nicht notwendig, um die Prinzipien dieses Tutorials zu befolgen, aber seien Sie sich bewusst, dass Sie jeden Code an Ihre eigene Einrichtung anpassen müssen.

Sind Sie also bereit mit Ihrer lokalen Einrichtung?

Großartig!

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, geht es bei der WordPress REST API darum, Gespräche zu ermöglichen.

Wir werden also die WordPress REST API verwenden, damit die beiden Websites miteinander sprechen und Daten austauschen können.

Und das Endziel des Tutorials ist:

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

Für diesen Artikel wird die Hilfe-Center-Website, die alle Wissensdatenbankartikel enthält, als 'lokale' Website bezeichnet und die neue Website, auf der Sie das Widget anzeigen werden, als 'externe' Website.

An diesem Punkt gehe ich davon aus, dass Sie 1) Ihre 'lokale' Hilfe-Center-Website und 2) eine neue 'externe' Website auf einem anderen Server eingerichtet haben.

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

Damit sind wir bereit zu beginnen:

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

Sehen Sie den vollständigen Code für dieses WordPress REST API Tutorial hier.

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

Indem wir den Code oben in der Vorlage hinzufügen und im Plugins-Verzeichnis speichern, haben wir ihn als Plugin erstellt (anstatt den Code in die functions.php-Datei des Themes einzufügen).

Es ist eine Kleinigkeit, aber das Erstellen eines Widgets als Plugin in diesem Stil ermöglicht es Ihnen, es ein- und auszuschalten und es später bei Bedarf auch in anderen Themes wiederzuverwenden, ohne kopieren und einfügen zu müssen.

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

Schritt #2: Verwenden Sie die WordPress REST API, um die neuesten Wissensdatenbankartikel abzurufen

Da Sie bei dieser Entwicklung nichts bearbeiten oder löschen möchten, konzentrieren wir uns nur auf die widget()-Funktion. Hier werden die Inhalte des Widgets auf der „externen“ Website ausgegeben.

Um die Liste der neuesten Wissensdatenbankartikel von der „lokalen“ Website zu „erhalten“, müssen wir ein paar 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 ausgeführt werden soll)
• Parameter (Die Daten, die mit der Anfrage verbunden sind)

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/

Über die Endpunkte: Diese Route hat tatsächlich drei Endpunkte, die durch die HTTP-Methoden unterschieden werden. Diese Endpunkte sind:

• GET
• PUT
• DELETE

In diesem Beispiel wählen Sie den GET-Endpunkt, um eine Liste der neuesten Beiträge von der 'lokalen' Website abzurufen (oder zu 'holen').

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

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

Überprüfen Sie als Nächstes, 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, gibt es keinen Fehler.

Der letzte Teil dieses Abschnitts ist:

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

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

$response ist ein JSON-kodierter String mit Post-Daten. Sie dekodieren ihn also nur, damit er ausgegeben werden kann.

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

An diesem Punkt haben Sie erfolgreich mit Ihrer 'lokalen' Website über die API kommuniziert. Diese Implementierung liefert Ihnen eine Liste von Beiträgen zur Anzeige.

Die nächste Stufe ist die tatsächliche Anzeige in Ihrem Widget auf der 'externen' Website.

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 wie folgt aussehen:

Nachdem der obige Schritt abgeschlossen ist, sehen Sie, wenn Sie nun versuchen, Ihre 'externe' Website anzuzeigen, eine Liste Ihrer Beiträge von der 'lokalen' Website in Ihrer Seitenleiste.

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, da das Knowledge Base Plugin seinen eigenen benutzerdefinierten Post-Typ verwendet. Und da benutzerdefinierte Post-Typen 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)

Verwendung der REST-API mit benutzerdefinierten Beitragstypen

Um benutzerdefinierte Post-Typen für die REST API verfügbar zu machen, benötigen Sie einen kleinen Workaround.

Wenn Sie also einen benutzerdefinierten Beitragstyp erstellen, müssen Sie den Argumenten für die Registrierung des Beitragstyps einen neuen Parameter hinzufügen, um ihn öffentlich verfügbar zu machen:

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

Da wir in unserem Fall jedoch ein Plugin zur Verwaltung des Post-Typs für Wissensdatenbankartikel verwenden, werden wir die Plugin-Datei nicht direkt bearbeiten, um die benutzerdefinierten Post-Typen für die REST API verfügbar zu machen. (Das direkte Bearbeiten einer Plugin-Datei ist nie eine gute Idee!)

Was wir stattdessen tun werden, ist, den folgenden Code zur functions.php-Datei im Child-Theme für die 'lokale' Website hinzuzufügen:

<?php

if ( ! defined( 'ABSPATH' ) ) exit;

/**
* 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' für die WP REST API öffentlich verfügbar.

Nachdem wir den benutzerdefinierten Beitragstyp für die WordPress REST API verfügbar gemacht haben, müssen wir nun unser Widget reparieren, um Beiträge mit diesem Beitragstyp anzuzeigen. Dazu gehen wir zurück zum $response-Code aus Schritt Nr. 2 und aktualisieren ihn auf:

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

Wir ändern im Grunde /posts/ zu /ht_kb/ in der API-Route, da 'ht_kb' der Name des benutzerdefinierten Beitragstyps des Plugins ist.

Nachdem Sie Ihr Widget aktualisiert und die 'externe' Website in der Vorschau angezeigt haben, sollten Sie nun die neuesten Artikel aus der Wissensdatenbank sehen.

Abschließende Gedanken

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

Sie könnten das gerade erstellte Plugin ändern, um eine Suchleiste zu erstellen, die die WP REST API verwendet, um die Artikel der Wissensdatenbank zu durchsuchen und die Ergebnisse im Widget anzuzeigen.

Oder Sie könnten die Authentifizierung nutzen, 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! Beherrschen Sie einfach die Grundlagen, und Sie sind bestens gerüstet.

Weiterführende Lektüre

Es gibt viele veraltete Inhalte zur WordPress REST API, stellen Sie also sicher, dass Sie nur die aktualisierten Dinge lesen. Ich habe im gesamten Beitrag auf einige nützliche Ressourcen verlinkt, aber ich liste hier auch einige auf.

Lesen Sie sich also ein und finden Sie die verschiedenen kreativen Möglichkeiten heraus, wie Sie die REST API nutzen können.

• REST API Handbuch
• REST-API-FAQs

Wenn Sie Fragen zur Implementierung der WordPress REST API haben, stellen Sie diese unten in den Kommentaren!