REST-Feld allgemein

Folgende Funktion registriert ein neues Feld zu einem existierenden Objekt in WordPress:

<?php
function register_rest_field( $object_type, $attribute, $args = array() ) {
	...
}
?>

Es gilt:

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

An die Funktion oder die Methode, die über den get_callback-Parameter festgelegt wurde, werden folgende Parameter übergeben (der Reihe nach):

• $object (object)
  Das Objekt, auf das Zugegriffen wird. Bei einem Kommentar wäre das das Kommentar-Objekt. Bei einem Post das WP_Post-Objekt.
• $field_name (string)
  Der Name des Feldes, welches registriert wurde.
• request (WP_Rest_Request)
  Das Objekt des aktuellen REST-Requests.
• object_type (string)
  Die Bezeichnung des aktuellen Objekttyps. Bei einem Kommentar wäre das zum Beispiel comment. Bei einem Beitrag post.

An die Funktion oder die Methode, die über den update_callback-Parameter festgelegt wurde, werden folgende Parameter übergeben (der Reihe nach):

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

Gibt die update_callback-Funktion ein WP_Error-Objekt zurück, reagiert die REST-API entsprechend darauf, bricht ab und gibt die Fehlermeldung aus.

Beispiel:

Nehmen wir an, wir nutzen ein Plugin welches es zulässt, dass Kommentare bewertet werden können. Der Gesamtwert (ein int) wird dabei als Kommentar-Meta mit dem Schlüssel comment_karma gespeichert.

Hinweis
Tatsächlich hat WordPress das Feld comment_karma schon vorgesehen. Es nutzt es aber nicht. Vermutlich haben sich die Entwickler einmal gedacht, dass das ohnehin Sache von Plugins wäre. Wie dem auch sei. Wir können das Feld für unsere Zwecke nutzen

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

Wenn wir nun einen REST-API-Abruf auf http://test.local/wp-json/wp/v2/comments/{comment_id} starten, sehen wir, dass das Karma-Feld ausgeliefert wird:

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

Über das Argument schema können wir weitere Informationen ausgeben damit dem Benutzer klar ist, wofür karma genau steht. Dazu verändern wir mm_init wie folgt:

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

Rufen wir jetzt http://test.local/wp-json/wp/v2/ auf, sehen wir, dass unsere Daten hier auftauchen:

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

Wenn wir einen POST-Request an http://test.local/wp-json/wp/v2/comments/1 senden und karma als Parameter übergeben, erhalten wir zwar keinen Fehler aber die Daten werden auch nicht gespeichert. Das liegt daran, dass WordPress nicht weiß, was mit den Daten passieren soll. Das legen wir nun wie folgt fest:

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

Beachten Sie, dass wir nun auch schema angepasst haben. Und zwar haben wir über context angezeigt, dass der Wert nun auch überschrieben werden kann. Darüber hinaus haben wir eine sanitize_callback-Funktion übergeben, die auf den neuen Wert angewendet wird, bevor dieser in der Datenbank landet.

REST-Meta-Feld

Wie bereits in einem früheren Kapitel angesprochen gibt es auch noch die Funktion register_meta() die es Ihnen erlaubt, die Response eines Endpunkts zu erweitern. Zur Wiederholung: man muss den $args-Parameter namens show_in_rest auf true setzen damit die REST-API das Meta-Feld aufnimmt.

Wir bauen obiges Beispiel nach, jedoch nutzen wir jetzt anstatt register_rest_field() nun die register_meta()-Funktion.

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

Der Code ist deutlich schlanker geworden. Senden wir ein GET-Request an http://test.local/wp-json/wp/v2/comments/{comment_id} wird comment_karma nun unter meta aufgelistet:

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

Ein Update wird ebenfalls korrekt getriggert, wenn wir einen POST-Request an die selbe URL senden. Dann muss man meta['comment_karma] mit dem gewünschten Wert übergeben.

Welche Funktion soll verwendet werden?

Wie Sie sich vielleicht denken können, machen die beiden Funktionen in etwa das gleiche: sie machen Daten in der REST-API sichtbar. Der Unterschied ist, dass Sie mit register_rest_field() Ihre eigenen Callback-Funktionen für das Speichern und Aktualisieren bereitstellen müssen während ein Feld, welches mit register_meta() registriert wurde, bereits die von WordPress vordefinierten Callbacks nutzt. Sie müssen lediglich noch dafür sorgen, dass der Benutzer die korrekten Rechte hat und der Eingabewert entsprechend serialisiert wird.

Ein Nachteil von register_meta() ist, dass bis WordPress 4.9.8 alle Posttypen den selben Meta-Schlüssel erhielten. Registrierten Sie einen Meta-Schlüssel, so war dieser in jeder REST-Response enthalten.

Wenn Sie davon ausgehen können, dass WordPress größer oder gleich 4.9.8 läuft, haben Sie aber die Möglichkeit, einen so genannten Subtype zu wählen der sich auch auf die einzelnen Posttypen (page, post, etc.) ausrichten lässt.

Der zweite Nachteil von register_meta() ist, dass es nur skalare Werte annehmen kann. Dementsprechend erwartete es eine Typenübergabe beim Registrieren. Objekte oder Arrays kann es nicht verarbeiten. Deswegen müssen Sie hier auf register_rest_field() zurückgreifen.

Hinweis
Sie sollten niemals die Kern-Rückgabewerte von WordPress so modifizieren, dass sie vom Standard abweichen. Löschen Sie daher keine Felder sondern gehen Sie immer davon aus, dass andere Plugins und Themes auch die REST-API nutzen und auf die Standard-Daten möglicherweise angewiesen sind.