FSWP API-Entwickler

Was macht FSWP API-Entwickler?

Grundlegend (immer anzuwenden): fswp-developer/references/lean-coding.md (weniger schreiben, erstes wiederverwenden), fswp-developer/references/coding-standards.md (Codierungsstandards, Dokumentation, i18n, Barrierefreiheit) und fswp-security-engineer (Eingabe, Ausgabe, Autorisierung).

Offizielle Referenz: REST-API-Handbuch (fswp-developer/references/official-docs.md). Sicherheitsregeln aus fswp-security-engineer gelten für jede Route.

Eine Route registrieren

function vp_register_routes() {
	register_rest_route( 'vendor-prefix/v1', '/items/(?P<id>\d+)', array(
		'methods'             => WP_REST_Server::READABLE,
		'callback'            => 'vp_get_item',
		'permission_callback' => function ( WP_REST_Request $r ) {
			return current_user_can( 'edit_post', (int) $r['id'] );
		},
		'args'                => array(
			'id' => array( 'type' => 'integer', 'required' => true, 'sanitize_callback' => 'absint' ),
		),
	) );
}
add_action( 'rest_api_init', 'vp_register_routes' );

Regeln

• Namespace und Version: vendor-prefix/v1. Niemals im Core-Namespace wp/v2 registrieren.
• permission_callback ist obligatorisch. Gib eine Berechtigungsprüfung zurück, nicht nur den Anmeldestatus. Verwende __return_true nur für wirklich öffentliche Daten, mit einem Kommentar, der dies erklärt. Prüfe objektbezogenen Zugriff (edit_post, Eigentümerschaft), wenn eine ID in der Anfrage enthalten ist.
• Deklariere args mit type, required, enum, minimum/maximum, validate_callback und sanitize_callback. Die Anfrage ist auch nach der Validierung nicht vertrauenswürdig; verwende Werte aus $request->get_param() mit dem korrekten Typ.
• Daten mit rest_ensure_response() zurückgeben; Fehler als new WP_Error( 'vp_code', __( 'Nachricht', 'text-domain' ), array( 'status' => 404 ) ). Verwende genaue Statuscodes (400 ungültig, 401 nicht authentifiziert, 403 verboten, 404 nicht gefunden, 409 Konflikt, 413 zu groß).
• Schema: Implementiere get_item_schema() (oder schema-Callback), damit Clients und der Index die Ressource beschreiben können; forme Antworten mit prepare_item_for_response().
• Sammlungen: Unterstütze page/per_page mit einem harten Limit, setze X-WP-Total und X-WP-TotalPages und gib niemals unbegrenzte Listen zurück.
• Gib niemals Geheimnisse, Passwort-Hashes, rohe Optionen oder private Daten anderer Benutzer zurück.
• Controller: Verwende für mehr als ein paar Routen WP_REST_Controller (mit register_routes, get_items, get_item, create_item, Berechtigungsprüfungen pro Methode) und registriere die Klasse einmal.
• Kernobjekte verfügbar machen: Benutzerdefinierte Beitragstypen und Taxonomien mit 'show_in_rest' => true (und rest_base); Meta mit register_meta()/register_post_meta() und 'show_in_rest' => true sowie einem Schema und einem auth_callback.
• Caching und Leistung: Günstige GET-Handler; teure Ergebnisse cachen (fswp-performance-engineer); Abfragen in Schleifen vermeiden.

Authentifizierung

Client	Methode
JavaScript von derselben Site (Admin, Blöcke, Frontend)	Cookie-Auth mit dem X-WP-Nonce-Header (wp_create_nonce( 'wp_rest' ) oder wp_localize_script / @wordpress/api-fetch, was diesen automatisch hinzufügt)
Externer Server oder Anwendung	Anwendungspasswörter über HTTPS oder ein geprüftes OAuth-Plugin
Öffentliches Lesen	Keine Authentifizierung, nur wenn die Daten öffentlich sind

Nonces ersetzen keine Berechtigungsprüfungen. CORS: Gib Access-Control-Allow-Origin: * nicht für authentifizierte Routen frei.

Clientseitig

Verwende @wordpress/api-fetch in Blöcken und Admin-Bildschirmen. Behandle Fehler anhand von code und message, nicht durch Textparsing.

Abilities API

Eine Core-API zum Registrieren diskreter, maschinenlesbarer Fähigkeiten (Name, Eingabeschema, Ausgabeschema, Berechtigungsprüfung, Ausführungs-Callback), die von Tools und KI-Agenten entdeckt und aufgerufen werden können. Sie ist neu: Bestätige die minimale WordPress-Version und die genauen Funktionsnamen in der Entwicklerdokumentation, bevor du sie verwendest (suche nach „Abilities API“). Verwende sie nur, wenn die PRD agentenaufrufbare Funktionen benötigt; normales REST ist für gewöhnliche Client-Server-Aufrufe geeignet.

Beim Registrieren einer Fähigkeit:

• Registriere zuerst die Kategorie, dann die Fähigkeit, an den dokumentierten Hooks.
• Gib ihr JSON-Schemas für Ein- und Ausgabe sowie einen permission_callback, der eine echte Berechtigung prüft.
• Gib die Sicherheitsannotationen ehrlich an: Schreibgeschützte Fähigkeiten dürfen nicht schreiben, destruktive müssen markiert sein. Ein Callback, der schreibt, während er als schreibgeschützt annotiert ist, ist ein Fehler, und fswp-reviewer behandelt ihn als solchen.
• Mache über REST nur das verfügbar, was aus der Ferne aufrufbar sein soll.

Audit- und Verifizierungsverfahren: references/abilities.md.

Um vorzuschlagen, welche vorhandenen Endpunkte zu Fähigkeiten werden sollten, liste jede Route mit ihrer Methode, der aktuellen Berechtigungsprüfung, den Nebenwirkungen und einer vorgeschlagenen Annotation auf; registriere nichts, bis es genehmigt wurde.