Ausführliche Anleitung zum Erstellen und Abrufen von benutzerdefinierten WP-REST-API-Endpunkten

Dieser Beitrag zeigt, wie man benutzerdefinierte WordPress-REST-Endpunkte und verschiedene Methoden zum Ausführen von Anfragen an sie erstellt. Es wird Beispiele in PHP, jQuery und Vanilla Javascript geben.

Ich gehe davon aus, dass Sie bereits mit der WP REST API vertraut sind, aber hier ist eine kurze Zusammenfassung. WordPress REST API ist eine JSON-Schnittstelle zum Senden und Empfangen von Daten von Ihrer WordPress-Site. Auf die Endpunkte (bestimmte Pfade/URLs) können Sie sowohl extern als auch intern zugreifen. WordPress verfügt bereits über eine Reihe von Endpunkten, z. B. zum Abrufen von Beiträgen, Kategorien, Durchsuchen der Website und mehr. Sehen Sie sich hier eine Übersicht der standardmäßigen WordPress-Endpunkte an. Entwicklern steht es jedoch völlig frei, mit dieser API ihre eigenen benutzerdefinierten Endpunkte zu erstellen, um entweder Aktionen auszuführen oder Daten abzurufen.

Wir beginnen mit dem ersten Schritt; die benutzerdefinierte Endpunkte erstellt. Wenn Sie nur daran interessiert sind, Anfragen zu stellen, fahren Sie mit dem zweiten Teil fort.

Erstellen Sie benutzerdefinierte Endpunkte

Die Registrierung benutzerdefinierter Endpunkte erfolgt in PHP. Sie können den Code zur Codedatei Ihres Designs functions.phpoder eines aktiven Plugins hinzufügen. Erstellen Sie eine verknüpfte Funktion rest_api_initund verwenden Sie die Funktion [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()für jeden Endpunkt, den Sie hinzufügen möchten.

Als ersten Parameter register_rest_route()müssen Sie einen eindeutigen Namespace angeben, um sicherzustellen, dass Ihre Endpunkte nicht mit anderen in Konflikt geraten. Verwenden Sie den Slug Ihres Themes oder Plugins. Es ist üblich, dann ein /gefolgt von einer Versionsnummer für Ihren Code einzufügen. Als Beispiel verwende ich den Namensraum awhitepixel/v1. Der zweite Parameter ist der Pfad (der dem Namespace folgt). Schließlich können Sie optional ein Array als dritten Parameter mit Optionen angeben. In diesem Array können Sie beispielsweise die Anforderungsmethode (GET, POST oder eine andere) definieren, Parameter definieren und vor allem die Funktion definieren, die ausgeführt werden soll, wenn dieser Endpunkt angefordert wird.

Als dritter Parameter sollten Sie mindestens die Argumente ‘method’ und ‘callback’ (das ist die Funktion zur Verarbeitung der Endpunktdaten) angeben. Für „Methode” können Sie sie als „ GET', 'POST', 'PUT', oder jede andere gültige Anforderungsmethode (oder ein Array aus mehreren) festlegen, aber ich empfehle, dafür die Standardeinstellungen von WordPress zu verwenden. Sie sind wie folgt:

• WP_REST_Server::READABLE Methode ‘ GET‘
• WP_REST_Server::EDITABLE Methoden ‘ POST‘, ‘ PUT‘ und ‘ PATCH‘
• WP_REST_Server::DELETABLE Methode ‘ DELETE‘
• WP_REST_Server::ALLMETHODS alle oben genannten Methoden

Lassen Sie uns einen einfachen benutzerdefinierten Endpunkt erstellen, der mit GET-Anforderungen erreicht werden kann:

In Zeile #2haben wir unseren benutzerdefinierten Endpunkt als „ awhitepixel/v1/getsomedata” definiert. Die vollständige URL wäre die REST-API-Stamm-URL von WordPress mit dem Präfix <yourdomain>/wp-json. Die vollständige URL zum obigen Endpunkt wäre also „ <yourdomain>/wp-json/awhitepixel/v1/getsomedata“. In Zeile #4haben wir einen Funktionsnamen als Callback angegeben, den wir in Kürze hinzufügen werden.

Wenn Sie REST-API-Routen mit registrieren (oder ändern) register_rest_route(), müssen Sie Ihre Permalinks leeren, damit es funktioniert. Sie können dies tun, indem Sie Einstellungen > Permalinks in Admin besuchen und einfach auf Speichern klicken.

Wir haben die Callback-Funktion noch nicht definiert – das ist die Funktion für den Code, der die Reaktion auf die Verwendung dieses Endpunkts handhabt. Es muss eine gültige REST-Antwort (in JSON) zurückgeben, sodass Sie etwas zurückgeben müssen, obwohl der Endpunkt keine Daten zurückgeben soll. Sie können die Funktion [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()function verwenden oder eine WP_REST_ResponseObjektinstanz als Rückgabe des Callbacks erstellen. Als Parameter für die Callback-Funktion erhalten wir ein WP_REST_RequestObjekt, das alle Informationen über die Anfrage enthält – einschließlich aller Parameter. Lassen Sie uns eine einfache Callback-Funktion erstellen, die einfach Text als Antwort sendet:

function awhitepixel_rest_route_getsomedata( $request) {
    $response = 'Hello there!';
    return rest_ensure_response( $response );
}

Dies ist die grundlegendste Art, einen Callback zu schreiben. Die Funktion rest_ensure_response()stellt sicher, dass alle von uns bereitgestellten Daten (die Zeichenfolge) in eine gültige REST-Antwort umgewandelt werden. Offensichtlich möchten Sie hier mehr Code hinzufügen, um entweder etwas in WordPress zu tun oder Daten abzurufen und zurückzusenden.

Mit dem obigen Code (Registrierung des Endpunkts und der Callback-Funktion) können Sie versuchen, die URL in Ihrem Browser aufzurufen und zu sehen, was Sie erhalten. (Denken Sie daran, Ihre Permalinks zu löschen). Wenn Sie <domain>/wp-json/awhitepixel/v1/getsomedataim Browser zu gehen, wird die Zeichenfolge „Hallo!” angezeigt.

Parameter übernehmen

Es ist sehr üblich und nützlich, Endpunkten das Akzeptieren von Parametern zu erlauben. Wenn Ihre Website beispielsweise Produktdaten enthält, möchten Sie einen Endpunkt, an dem Sie eine Produkt-ID angeben können, um die Daten dieses Produkts abzurufen. Es gibt zwei Möglichkeiten, dies zu tun. Die gebräuchlichste Methode ist die Verwendung von GET-Abfragezeichenfolgen (die nach der URL nach einem angehängt werden ?, getrennt durch &im Schlüssel=Wert-Format. Zum Beispiel ‘ <endpoint>/product/?product_id=14‘). Alternativ können Sie ein „schöneres” URL-Muster definieren, bei dem Parameter Teil des Pfads sind. Zum Beispiel ‘ <endpoint>/product/14/‘. Diese letzte Methode erfordert jedoch einige Kenntnisse über Regexes. Welche Methode Sie wählen, liegt bei Ihnen, ich werde beide unten demonstrieren.

GET-Parameter

Um mögliche GET-Parameter für Ihren Endpunkt zu definieren, verwenden Sie den argsSchlüssel ‘ ‘ im register_rest_route()dritten Parameter von. Definieren Sie für jeden Parameter, den Sie zulassen möchten, den Schlüsselwert (im obigen Beispiel „ product_id“) und ein Array von Optionen für diesen Parameter. Als Optionen können Sie das Format des Parameters definieren (wenn er beispielsweise eine Zahl oder einen String erwartet) und auch entscheiden, ob dieser Parameter erforderlich ist oder nicht.

Als Beispiel möchten wir unserem Endpunkt erlauben, „ product_id” als nicht erforderliche Nummer zu akzeptieren.

Wenn Sie einen Parameter in als wahr definieren required, wird WordPress eine 400-Fehlerantwort zurückgeben. Ebenso, wenn Sie einem Parameter, der eine Zahl erwartet, ein ungültiges Format übergeben, z. B. „Hallo” als Wert.

In der Zeile #15der Callback-Funktion sehen Sie, wie Sie den Parameterwert aus der Anfrage erhalten; Verwenden der Methode get_param()im übergebenen WP_REST_RequestObjekt. Als Beispiel zeige ich unterschiedliche Antworten, je nachdem, ob product_idbereitgestellt wurde oder nicht (denken Sie daran, dass wir dies als optional definiert haben). Die Logik der Änderung Ihres Codes gemäß den bereitgestellten Parametern liegt vollständig bei Ihnen und Ihrem Projekt. Sie können weniger Endpunkte haben, die viele Parameter akzeptieren, oder viel mehr separate Endpunkte für jeden speziellen Fall.

Mit dem obigen Code bekomme ich „Hallo!” wenn <yourdomain>/awhitepixel/v1/getsomedataich auf gehe und „Produktdaten für ID 14 zurücksenden”, wenn ich auf gehe <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.

Parameter als Teil des Pfads

Wenn Sie zulassen möchten, dass Parameter Teil des Pfads sind und nicht die Abfragezeichenfolge GET, können Sie dies tun. Anschließend geben Sie im Pfad ein Regex-Muster an – den zweiten Parameter von register_rest_route().

Das Erstellen von Regex-Mustern kann ziemlich kryptisch aussehen, aber da es sich um ein ganzes Thema handelt, finden Sie leicht Beispiele für bestimmte Fälle, wenn Sie es googeln. Ich zeige ein Beispiel für die Definition einer Regex, die eine Zahl beliebiger Länge akzeptiert;

Wie Sie in Zeile 2 sehen können, habe ich das Regex-Muster (?P<product_id>[d]+)am Ende hinzugefügt. Dieses Muster bedeutet, dass wir eine Zahl (d) beliebiger Länge (+) sammeln und den gesammelten Wert dem Parameter key zuweisen sollen product_id. Und in unserer Callback-Funktion verwenden wir genau dieselbe Methode wie beim Einrichten von GET-Parametern; get_param()in dem WP_REST_Requestfür die Funktion bereitgestellten Objekt.

Mit dem obigen Code (nach dem Leeren der Permalinks) können wir die URL besuchen <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14, um unsere Antwort zu erhalten. Diese Methode führt sicherlich zu „schöneren” URLs, aber der Code kann leicht schwieriger zu lesen und zu beheben sein. Für welche Methode Sie sich entscheiden, bleibt Ihnen überlassen.

Rückgabe der richtigen Antwort

Zuvor habe ich kurz erwähnt, wie die Callback-Funktion eine ordnungsgemäße REST-Antwort zurückgeben muss. Bisher haben wir die einfachere verwendet rest_ensure_response(). Aber manchmal möchten Sie vielleicht mehr Kontrolle über die Rückgabe Ihres Endpunkts. Sie möchten beispielsweise den Statuscode der HTTP-Antwort steuern. Angenommen, Sie erstellen einen Endpunkt, an dem Sie eine Produkt-ID angeben und Daten für dieses Produkt abrufen können. Wenn diese Produkt-ID jedoch nicht vorhanden war oder andere Parameter Verwirrung stiften, möchten Sie möglicherweise einen Statuscode von beispielsweise 400 (Fehlerhafte Anfrage) oder 404 (Nicht gefunden) zurückgeben. Oder vielleicht 500 (Serverfehler). Immer 200 (Erfolg) zu übergeben, obwohl die Anfrage schlecht war, kann auf der Seite des Absenders zu Problemen führen.

Ich würde dann Ihre Callback-Funktion empfehlen, die ein WP_REST_ResponseObjekt zurückgibt. Mit diesem Objekt können Sie mehrere Dinge steuern, einschließlich des Statuscodes. Es ist einfacher als Sie denken! In der einfachsten Form würden Sie eine neue Instanz von erstellen WP_REST_Response, ein Array der zurückzugebenden Daten als ersten Parameter und den Statuscode als zweiten Parameter bereitstellen. Als Beispiel:

Im obigen Beispiel speichern wir die Rückgabe der awhitepixel_get_product()Funktion in einer Variablen. Diese Funktion existiert nicht, und Sie sollten sie durch die Funktion ersetzen, die die gewünschten Aktionen in Ihrem Projekt abrufen (oder ausführen) soll. Angenommen, die Funktion gibt ein leeres Array zurück, und das bedeutet, dass etwas schief gelaufen ist (z. B. Produkt existierte nicht). Wir könnten dann ein WP_REST_ResponseObjekt mit dem Statuscode 400 und optional eine Nachricht als Daten zurückgeben, die erklärt, warum es fehlgeschlagen ist (Zeile #5-9). Andernfalls geben wir die Daten mit dem Statuscode 200 Success (Zeile #10) zurück.

Senden von Anfragen an (benutzerdefinierte) Endpunkte

Kommen wir zur anderen Seite, dem sendenden Teil: So senden Sie Anfragen an unsere benutzerdefinierten Endpunkte. Normalerweise würden Sie WP-REST-API-Anforderungen mit Javascript senden, und hier finden Sie Beispiele für die Verwendung von jQuery, der WordPress-Bibliothek und Vanilla-Javascript. Es ist ungewöhnlich, aber möglich, eine REST-Anfrage auch mit PHP durchzuführen – daher habe ich auch dafür ein Beispiel beigefügt.

Als Erstes müssen Sie sich bewusst sein, dass Sie natürlich die vollständige URL kennen müssen, um eine Anfrage zu senden. Ich empfehle nicht, die Domain (vor dem Endpunkt) fest zu codieren, da es mehrere Möglichkeiten gibt, dies zu erhalten, wenn Ihr Javascript in WordPress ausgeführt wird. In älteren Versionen von WordPress müssten Sie [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()in PHP verwenden und die Kern-REST-URL als globale Javascript-Variable übergeben. Die folgenden Beispiele zeigen jedoch eine neuere und bessere Möglichkeit, die REST-Stamm-URL der WordPress-Site abzurufen.

Eine weitere zu beachtende Sache ist, dass Sie für Ihr Projekt die Anforderungen wahrscheinlich als Ergebnis einer Aktion umschließen würden. Um die Dinge einfach zu halten, mache ich alle Anfragen bei DOM bereit, also sollten Sie sicherstellen, dass Sie den Anfragecode z. B. als Ergebnis des Klickens eines Besuchers auf eine Schaltfläche einschließen.

Verwendung von jQuery

Wenn Sie die jQuery-Bibliothek haben und verwenden möchten, können Sie ihre [$.ajax](https://api.jquery.com/jquery.ajax/)()Funktion verwenden.

Aber zuerst ein Hinweis zu den Abhängigkeiten Ihrer Javascript-Datei. Offensichtlich würde Ihr Skript eine 'jquery'Abhängigkeit benötigen, um es in die Warteschlange einzureihen. Aber um einfach auf die REST-Stamm-URL Ihres WordPress zugreifen zu können, fügen Sie eine weitere Abhängigkeit hinzu; ‘wp-api-request’. Dadurch wird sichergestellt, dass die Javascript-Variable wpApiSettings.rootverfügbar ist und die REST-API-Stamm-URL enthält. Hier ist ein Beispiel dafür, wie Sie Ihr Skript in die Warteschlange einreihen würden, um diese Abhängigkeit zu veranschaulichen.

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'jquery', 'wp-api-request' ], 
        null, 
        true
    );
} );

Line #5ist das Interessante; wobei wir sowohl jQuery als auch wp-api-requestals Abhängigkeit definieren. Dann können wir in unserer Javascript-Datei eine WP-REST-API-Anfrage wie folgt durchführen:

( function( $) {
    // Send request
    $.ajax( {
        url: wpApiSettings.root + 'awhitepixel/v1/getsomedata',
        method: 'GET',
        data: {
            product_id: 14
        },
        success: function( data) {
            console.log( data );
        }
    } );
} )( jQuery );

Dies ist so einfach wie es nur geht. Wir verwenden $.ajax(), um eine GET-Anfrage an die definierte URL zu senden. Als URL verwenden wir wpApiSettings.root, um die REST-API-Stamm-URL zu erhalten, und hängen dann den gewünschten Endpunkt dahinter an; in unserem Fall der benutzerdefinierte Endpunkt, den wir zuvor erstellt haben. Optional können wir Parameter in ‘data’ übergeben. Das obige Beispiel geht product_idmit dem Wert 14 an den Endpunkt. Schließlich successerhalten wir in der Funktion die (erfolgreiche) Anfrage als Parameter und können damit machen, was wir wollen. Im obigen Beispiel drucken wir es einfach auf der Konsole aus.

Verwenden der WordPress-Bibliothek (nicht jQuery)

Wenn Ihre WordPress-Site die jQuery-Bibliothek nicht hat oder verwenden kann, können Sie die Javascript-Bibliothek von WordPress verwenden, um einfach eine REST-API-Anforderung auszuführen. Die Funktion ist im globalen Namespace apiFetchvon WordPress verfügbar. ist eine Wrapper-Methode für die Browser-Standardfunktion (die als nächstes demonstriert wird).wp``wp.apiFetch()``fetch()

Unser Javascript benötigt die Abhängigkeit ‘wp-api’, um wp.apiFetch() verwenden zu können. Zum Beispiel könnten wir das Skript wie folgt in die Warteschlange stellen:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api' ], 
        null, 
        true
    );
} );

Sie finden die kritische Abhängigkeit in Zeile #5. Damit haben wir sichergestellt, dass unsere Javascript-Datei wp.apiFetch()verfügbar ist. Hier ist ein einfaches Beispiel für die Verwendung:

Denken Sie daran, dass Zeilen #9-13nur logisch sind, um die Funktion auszuführen, nachdem DOM bereit ist.

Ein Vorteil der Verwendung wp.apiFetch()gegenüber dem Normalen fetch()besteht darin, dass wir „path” verwenden können, das nur den Endpunkt erfordert, anstelle von „url”, das die vollständige URL erfordert. Ein weiterer Vorteil besteht darin, dass die erste „Kette” .then()die Daten bereits im JSON-Format zurückgibt. Wenn Sie das Original verwenden .fetch(), benötigen Sie mehr „.then()-Ketten”. Werfen Sie einen Blick auf das nächste Beispiel („Using Vanilla Javascript”), um zu sehen, was ich meine.

Denken Sie daran, dass fetch()(und folglich wp.apiFetch()) keine „saubere” Möglichkeit zum Übergeben von Parametern bietet. Wir müssen die GET-Abfragezeichenfolge manuell in „Pfad” erstellen, wie ich es oben getan habe: '../getsomedata?product_id=14'.

Wenn Sie daran interessiert sind, wie man wp.apiFetchEndpunkte in einen Gutenberg-Block einbindet und benutzerdefinierte, habe ich dazu ein separates Tutorial geschrieben:

Verwendung von Vanille-Javascript

Als letztes Beispiel für Javascript-Methoden zum Senden von Anfragen an die WP-REST-API gibt es einen reinen Vanilla-Nicht-WordPress-Weg, der fetch(). Bitte beachten Sie, dass ich die globale WordPress-Variable verwende, um die REST-Stamm-URL zu erhalten. Wenn Sie dieses Skript außerhalb von WordPress hinzufügen, müssen Sie wahrscheinlich die vollständige URL hartcodieren.

Da ich immer noch Zugriff auf die globale Variable für die WP-REST-Root-URL haben möchte, füge ich 'wp-api-request'meiner Javascript-Enqueuing-Funktion eine Abhängigkeit hinzu, wie folgt:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api-request' ], 
        null, 
        true
    );
} );

Und dann wäre in unserer Javascript-Datei ein grundlegendstes Beispiel:

Wie oben erwähnt („WordPress-Bibliothek verwenden”) .fetch()unterstützt es keine schöne, saubere Art der Parameterbereitstellung. Daher müssen Sie die Abfragezeichenfolge („?product_id=14″) manuell in die URL einbauen.

Denken Sie daran, dass die Abrufanforderung nicht direkt mit den Daten zurückkehrt – sie gibt ein Versprechen zurück. Deshalb müssen wir „ .then()” verketten, bevor wir mit den Daten umgehen können. Wenn Ihnen das ungewohnt vorkommt, empfehle ich, nachzuschlagen, wie man damit arbeitet fetch()– es gibt viele Erklärungen und Beispiele bei Google, die es besser erklären können als ich.

Wenn Sie den Statuscode der REST-Antwort auf Ihre Anfrage überprüfen möchten, können Sie dies so tun;

Im obigen Beispiel zum Registrieren benutzerdefinierter Endpunkte habe ich erwähnt, wie Sie verschiedene HTTP-Statuscodes zurückgeben können. Der obige Code zeigt ein Beispiel dafür, wie der Statuscode der Antwort überprüft wird, der in der Eigenschaft des zurückgegebenen Objekts verfügbar ist .status. Im obigen Beispiel überprüfe ich, ob der Statuscode in Zeile anders als 200 (Success) ist #5. Nur wenn der Statuscode 200 war, konvertiere ich die Datenrückgabe des Versprechens in JSON (Zeile #9).

Verwendung von PHP

Es ist weniger üblich, aber immer noch möglich, REST-Anforderungen intern in WordPress mit PHP auszuführen. Hier ist wie.

Um eine WP-REST-API-Anfrage in PHP zu senden, erstellen wir ein WP_REST_RequestObjekt (genau wie das, was weiter oben in diesem Beitrag an unsere Callback-Funktion übergeben wird). In dieser Objektinstanz definieren wir Methode (zB GET) und Endpunktpfad. Optional können wir auch Parameter hinzufügen. Dann verwenden wir die WordPress-Funktion [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()mit dieser Anforderungsinstanz. Schließlich erhalten wir die Antwort mit der in der s-Klasse [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()verfügbaren Funktion .WP_REST_Server'

Der Funktionsaufruf set_query_params()(Zeile #3-5) ist optional und nur notwendig, wenn Sie Parameter übergeben wollen. Nach dem roten Faden in diesem Beitrag werde ich ein Beispiel für die Übergabe des Parameters der Funktion an den REST-Parameter key einfügen product_id.

Line #6ist, wo wir die Anfrage senden. Und in Zeile #7geben wir die Daten der Antwort zurück. Wenn wir also beispielsweise diese PHP-Funktion aufrufen awp_do_php_rest_request( 14 )würden, würden wir die Antwort erhalten, die wir in diesem Endpunkt definiert haben (ein Array mit einer Zeichenfolge, wenn Sie immer noch dasselbe Beispiel wie am Anfang dieses Beitrags verwenden).