20.4.3. Eigene Endpunkte

Wie bereits erwähnt muss man sich nicht nur auf die vorhandenen REST-Routen und Endpunkte beschränken, man kann diese selbst erweitern. Dazu müssen Routen registriert werden. Das gelingt mit folgender Funktion:

<?php
function register_rest_route( $namespace, $route, $args = array(), $override = false ) {
	...
}

Es gilt:

Dieser Inhalt ist nur eingeschränkt verfügbar. Melden Sie sich vorher an.

Die Funktion gibt true im Erfolgsfall zurück. false entsprechend im Fehlerfall.

Beispiel im einfachsten Fall:

Dieser Inhalt ist nur eingeschränkt verfügbar. Melden Sie sich vorher an.

Bei Github ansehen

Namespaces

Den Namespaces setzen wir aus zwei Teilen zusammen. Einer von uns gewählten Bezeichnung, die nicht mit anderen Plugins kollidieren soll (hier also rating_plugin), gefolgt von einer Versionsnummer (hier v1).

Falls Sie irgendwann grundlegende Änderungen am Endpunkt durchführen, können Sie die alte Route bestehen lassen und die Versionsnummer um 1 erhöhen.

Routenbezeichnungen

Wir haben die Route /comments/ratings genannt. Der volle Aufruf lautet dann http://test.local/wp-json/rating_plugin/v1/comments/ratings.

Die WordPress-Dokumentation empfiehlt, am Anfang der Routenbezeichnung die Ressource selbst anzugeben. Somit wäre immer klar, mit was man interagiert. Bei Kommentaren wäre also comments angebracht.

In der Routenbezeichnung lassen sich auch so genannte Pfadvariablen einbetten. Sie bestehen aus einem regulären Ausdruck, wie im folgenden Beispiel zu sehen ist:

Dieser Inhalt ist nur eingeschränkt verfügbar. Melden Sie sich vorher an.

Endpunkte

Nun kommen wir zu den eigentlichen Endpunkten. Wir erinnern uns: ein Endpunkt besteht aus der Route mit der Request-Methode. Gehen wir noch einmal näher darauf ein, was wir im ersten Beispiel gemacht haben:

Über den $args-Parameter im Funktionsaufruf haben wir ein folgendes Array übergeben:

array(
	'methods'  => 'GET',
	'callback' => 'get_ratings',
)

Das teilte der REST-API mit, dass die Route über einen GET-Aufruf erreichbar ist. Darüber hinaus leitet sie die Anfrage an die Funktion get_ratings() weiter. Wir können aber noch weitere Array-Schlüssel übergeben:

Es gilt

Dieser Inhalt ist nur eingeschränkt verfügbar. Melden Sie sich vorher an.

Hinweise:

  1. context ist etwas schwierig zu verstehen. Es beschreibt der Parameter in welchen Context die Rückgabe steht.  Weston Ruter hat dazu einen gesamten Blogbeitrag geschrieben (englisch). Wird beispielhaft der Context edit übergeben, so erwartet die anfragende Ressource die Rückgabe der Rohdaten die zum Bearbeiten genutzt werden können.
  2. Wenn Sie sanitize_callback nicht angeben, wird das interne System der REST-API aktiviert. Allerdings nur, wenn ein type für eine Variable vorgesehen wurde.

Hilfreich
Die Klasse WP_REST_Server hat vier Konstanten, auf die Sie zurückgreifen können:

Dieser Inhalt ist nur eingeschränkt verfügbar. Melden Sie sich vorher an.

Sehen wir uns ein Beispiel an um das ganze zu verdeutlichen. Ich habe versucht, durch Kommentare das Beispiel etwas verständlicher zu machen:

Dieser Inhalt ist nur eingeschränkt verfügbar. Melden Sie sich vorher an.

Beispiel 2:

Nehmen wir an, wir wollen mehrere Bewertungen zu verschiedenen Kommentaren anfordern. Dann könnten wir folgendes tun:

Dieser Inhalt ist nur eingeschränkt verfügbar. Melden Sie sich vorher an.

Beispiel 3: Nehmen wir noch ein komplexeres Beispiel welches zeigt, wie mehrere Endpunkte in einer Route zusammengefasst werden können:

Dieser Inhalt ist nur eingeschränkt verfügbar. Melden Sie sich vorher an.