Registrieren Sie den Endpunkt im Namespace eines eigenen Plugins mit expliziten HTTP-Methoden, Argumenten, Validierung und einem Permission-Callback. Der Callback sollte einen separaten Anwendungsdienst aufrufen und ein stabiles Schema oder einen strukturierten WP_Error zurückgeben. Testen Sie anonyme und berechtigte Benutzer, Grenzwerteingaben, Paginierung und Abwärtskompatibilität. Geben Sie die Ausgabe über einen expliziten Resource-Transformer frei. Interne Meta-Felder sollten nicht automatisch zurückgegeben werden.
Ein eigener WordPress-REST-API-Endpoint stellt eine bestimmte Funktion der Website einer Anwendung, einer Integration oder einer eigenen Administrationsoberfläche zur Verfügung. Ein schneller Callback, der das Ergebnis einer Datenbankabfrage zurückgibt, kann im ersten Prototyp funktionieren, doch ohne stabilen Vertrag kann der Client weder Fehler unterscheiden noch Daten paginieren oder sicher auf eine neue Version umsteigen. Die Implementierung wird dann zu einer fragilen Kopplung an interne Details von WordPress.
Diese Anleitung konzentriert sich auf den Entwurf eines einzelnen eigenen Endpoints von der Anforderung bis zu den Tests. Die allgemeine Sicherheit und Performance der gesamten WordPress-REST-API-Ebene sind ein umfassenderes Thema. Hier behandeln wir Namespace, Route, Schema für Ein- und Ausgabe, Permission Callback, Fehlermodell, Vertragsänderungen und die Trennung der Anwendungslogik vom Transport.
Definieren Sie Quelle, Operation und Version der Route
Beschreiben Sie zuerst den Geschäftsvorgang und den Client. Das Lesen einer Projektliste, das Erstellen einer Anfrage und die Änderung eines Status sind unterschiedliche Routes mit unterschiedlichen Berechtigungen. Leiten Sie den URL-Namen von der Ressource ab, verwenden Sie die richtige HTTP-Methode und einen Namespace mit Version, der einem bestimmten Plugin oder einer Organisation gehört.
Der Vertrag umfasst Parameter, Typen, Pflichtangaben, Standardwerte, Ausgabe und Fehler. Legen Sie interne Tabellennamen oder serialisierte Meta-Werte nicht nur deshalb offen, weil sie leicht verfügbar sind. Das öffentliche Modell sollte auch nach einer Änderung des Speichers stabil bleiben. Dokumentieren Sie Beispiele ohne Produktions-Tokens und personenbezogene Daten.
Registrieren Sie Argumente und validieren Sie deren Bedeutung
Das Argument-Schema prüft Typ, Format, Wertebereich und zulässige Werte noch vor dem Callback. Die Sanitisierung stellt ein sicheres Format her, sollte aber eine ungültige geschäftliche Eingabe nicht stillschweigend in einen anderen Wert umwandeln. Ist ein Status unbekannt oder liegt ein Datum außerhalb des zulässigen Zeitraums, geben Sie einen konkreten Client-Fehler mit einem stabilen Code zurück.
Validieren Sie auch die Beziehungen zwischen Feldern. Ein Enddatum kann ein Startdatum erfordern, und ein Eintrag muss zu dem Objekt gehören, an das er angehängt wird. Laden Sie beim Schreiben den aktuellen Zustand unmittelbar vor der Änderung neu, damit der Client nicht mit einer längst ungültigen Annahme durchkommt. Ein Größenlimit schützt Text, Listen und Uploads.
- Typ, Bereich und zulässige Werte
- Bedeutungsbeziehungen zwischen Parametern
- Größenlimit der Anfrage
- Stabiler Fehlercode für den Client
Binden Sie den Permission Callback an Objekt und Aktion
Die Authentifizierung sagt nur aus, wer aufruft. Der Permission Callback entscheidet, ob die Person eine bestimmte Aktion an einem konkreten Objekt ausführen darf. Verwenden Sie Capabilities und eine Eigentumsprüfung statt einer Prüfung des Rollennamens. Wenden Sie bei Listen den Berechtigungsfilter in der Abfrage an, nicht erst nach dem Laden und Zählen aller Datensätze.
Eine Nonce eignet sich für Anfragen aus der angemeldeten WordPress-Oberfläche, ist aber kein universeller API-Schlüssel für einen externen Server. Wählen Sie die externe Authentifizierung nach dem unterstützten Mechanismus und schützen Sie die Übertragung mit HTTPS. Eine Fehlerantwort darf nicht verraten, ob ein sensibles fremdes Objekt existiert, wenn der Aufrufende dazu nicht berechtigt ist.
Trennen Sie Controller, Logik und Serialisierung
Der REST-Callback liest validierte Argumente, ruft einen Anwendungsservice auf und serialisiert das Ergebnis. Legen Sie Geschäftslogik nicht direkt in die Registrierung der Route; sonst lässt sie sich weder sinnvoll testen noch über CLI oder eine Queue nutzen. Der Service arbeitet mit Domänenwerten, und die Transportobjekte von WordPress bleiben am Rand.
Die Ausgabe bildet ein expliziter Resource Transformer, der nur festgelegte Felder zulässt. Datum, Währung und Zahlen haben ein einheitliches Format. Eine Liste verwendet ein Limit mit Obergrenze, eine stabile Reihenfolge und einen Paginierungsmechanismus. Laden Sie aufwendige abgeleitete Felder bedingt oder cachen Sie sie mit präziser Invalidierung.
Testen Sie den Vertrag und planen Sie kompatible Änderungen
Automatisierte Tests decken Erfolg, fehlende Parameter, ungültige Typen, Grenzwerte, anonyme Nutzer, unzureichende Berechtigungen und fremde Objekte ab. Testen Sie bei Schreibvorgängen Wiederholungen und Parallelität. Ein Integrationstest prüft die tatsächliche Route, Header, Statuscodes und JSON, nicht nur die interne PHP-Methode.
Das Hinzufügen eines optionalen Feldes ist in der Regel kompatibel, eine Bedeutungsänderung oder Entfernung dagegen nicht. Veröffentlichen Sie bei einer inkompatiblen Änderung eine neue Version der Route, beobachten Sie die Nutzung der alten und geben Sie den Clients Zeit für den Übergang. Dokumentation und Vertragstest werden zusammen mit dem Code aktualisiert. Überwachen Sie nach dem Deployment Fehler anhand eines stabilen Codes, nicht anhand des Inhalts sensibler Payloads.
Häufige Fragen
Braucht jeder REST-Endpunkt einen Permission Callback?
Ja, die Route sollte explizit über den Zugriff entscheiden. Ein öffentlicher Endpoint kann bewusst anonymes Lesen erlauben, definiert aber dennoch Umfang und Limits und darf nicht versehentlich nicht öffentliche Felder zugänglich machen.
Ist ein Nonce eine Authentifizierung für externe Anwendungen?
Eine Nonce wird vor allem bei einer angemeldeten WordPress-Sitzung verwendet und schützt den konkreten Kontext einer Anfrage. Eine externe Anwendung benötigt einen geeigneten, unterstützten Authentifizierungsmechanismus, sicheren Transport und eingeschränkte Berechtigungen.
Wann sollte eine neue Version einer REST-Route erstellt werden?
Wenn Sie Bedeutung, Pflichtfelder oder Ausgabe so ändern, dass ein bestehender Client nicht mehr funktionieren könnte. Eine kompatible Erweiterung kann der aktuellen Version hinzugefügt werden, wenn der Vertrag dies erlaubt und Tests es bestätigen.
Quellen und weiterführende Lektüre
Adam Antoni vyvíja weby, aplikácie a softvér na mieru. Prepája firemné systémy, automatizuje procesy a vytvára AI agentov. Pôsobí v Spišskej Novej Vsi a spolupracuje s firmami na celom Slovensku.
