Wie im Kapitel vorher beschrieben kann es manchmal nötig sein, eigene REST-API-Controller-Klassen zu erstellen oder auf die vorhandenen aufzubauen.
Controller-Klassen nehmen Anfragen eines Endpunkts entgegen, verarbeiten diese und geben danach etwas zurück. Alle von WordPress gelieferten Controller lassen sich in so genannte Infrastruktur- oder Endpunkt-Klassen unterscheiden. Dabei gilt:
Die WP_REST_Server-Klasse ist der Infrastrukturcontroller. Zu seinen Aufgaben gehören:
- Registrierung der Routen;
- Authentifizierung;
- Request-Validierung mit Erstellung eines
WP_REST_Request-Objekts; - Rechte-Checks;
- sowie Durchreichen der Anfrage an die Sub-Controller.
Wenn WP_REST_Server eine Anfrage erhält, generiert es ein WP_REST_Request-Objekt, welches dann an einen Sub-Controller durchgereicht wird. Das Objekt enthält alle Daten der ursprünglichen Anfrage. Das sind z.B. Header- und Formulardaten.
Erhält ein Sub-Controller die Anfrage, reicht er diese an seine entsprechenden Methoden weiter. Er entscheidet dies anhand der im WP_REST_Request-Objekt enthaltenen Daten. Die einzelnen Methoden wären dann die Endpunkte selbst. Deshalb nennt man die Sub-Controller dann auch Endpunkt-Controller.
Nehmen wir als Beispiel den in WordPress enthaltenen Artikeltyp post. Hier wäre die Klasse WP_REST_Posts_Controller der Endpunkt-Controller welcher von WP_REST_Server aufgerufen wird, wenn eine Anfrage an diesen Artikeltyp gestellt wird.
WP_REST_Posts_Controller erweitert die Klasse WP_REST_Controller um seine spezifischen Endpunkte (Methoden) zur Verarbeitung der Anfragen. Senden wir beispielhaft eine Anfrage an wp/v2/posts wird sie an die dortige Methode get_items() geschickt. Diese kümmert sich um die eigentliche Datenbank-Abfrage und sendet dann ein Objekt der Klasse WP_REST_Response zurück.
Mit WP_REST_Response schließt sich dann letztlich der Kreis. Sie erweitert die Klasse WP_HTTP_Response welche letztlich alle Daten enthält, die an das anfragende System zurück übermittelt werden sollen. Das sind zum einen natürlich die Daten selbst (in unserem Beispiel also eine gewisse Anzahl an Blogbeiträgen) aber auch zusätzliche Header-Daten wie der Status-Code.
Wer nun einen benutzerdefinierten Artikeltyp erstellt, kann die REST-API dazu zwingen, einen eigenen Controller statt den bisherigen zu verwenden. Zur Erinnerung: der Endpunkt-Controller für alle Inhaltstypen ist normalerweise die Klasse WP_REST_Posts_Controller. Man kann aber natürlich von dieser Klasse, oder aber auch von WP_REST_Controller ableiten um den eigenen Endpunkt-Controller zu entwerfen. Sehen wir uns beides einmal an.