Plugin REST-API

Das ist eine Entwickler-Referenz. Wenn du suchst, wie du Structura in wp-admin nutzt, beginne mit Dashboard-Tour — diese Seite ist für Leute, die Code gegen das Plugin schreiben.

Das WordPress-Plugin stellt REST-Endpunkte unter dem Namespace /structura/v1/channels/ bereit. Diese werden vom in wp-admin eingebetteten React-SPA konsumiert und sind aus jedem PHP-/JS- Code mit WordPress-Authentifizierungskontext und der Berechtigung manage_options nutzbar.

Quelle der Wahrheit: plugin/includes/Api/Rest_Api.php.

Endpunkte

Methode	Route	Handler	Cloud-Endpunkt
GET	`/channels/connections`	`channels_list_connections()`	`channelsListConnections`
POST	`/channels/connections/webhook`	`channels_save_webhook_connection()`	`channelsSaveWebhookConnection`
POST	`/channels/connections/credential`	`channels_save_credential_connection()`	`channelsSaveCredentialConnection`
DELETE	`/channels/connections/{connection_key}`	`channels_delete_connection()`	`channelsDeleteConnection`
GET	`/channels/events`	`channels_list_events()`	`channelsListEvents`
POST	`/channels/oauth/init`	`channels_oauth_init()`	`channelsOAuthInit`
GET	`/channels/catalog`	`channels_list_catalog()`	`channelsListCatalog`

Alle Routen erfordern die Berechtigung manage_options.

Handler-Muster

List Connections

Durchreichend zur Cloud. Gibt ein Array von ConnectionSummary-Objekten zurück. Geheimnisse sind nie enthalten — das Split-Doc-Design in Firestore stellt sicher, dass die Client-Sammlung von Natur aus sicher ist.

Save Webhook Connection

Sanitisiert Eingaben (integration_id, webhook_url, display_name, notification_locale, optional connection_id für Updates) und leitet dann an die Cloud weiter. Die Cloud validiert die URL über WebhookIntegration.validateTarget(), bevor sie verschlüsselt und persistiert wird.

Save Credential Connection

Sanitisiert die Schlüssel/Wert-Map der Zugangsdaten (jeden Schlüssel und Wert über sanitize_text_field) und leitet dann weiter. Die Form der Zugangsdaten variiert je Integration — das Plugin braucht kein Pro-Integration-Wissen, da die Cloud das Schema validiert.

Delete Connection

Akzeptiert entweder eine UUID (neue Verbindungen) oder eine Legacy-Integrations-ID (Verbindungen vor der Migration). Die Operation ist idempotent — das Löschen einer nicht existierenden Verbindung gibt Erfolg zurück.

List Events

Entpackt die Cloud-Antwort und gibt das nackte Event-Array zurück. Das Standard-Limit ist 25 Events, neueste zuerst.

List Catalog

Durchreichend, gibt den vollständigen Marktplatz mit Berechtigungs-Annotationen (canInstall, blocker pro Eintrag) zurück.

OAuth Init

Der interessanteste Handler. Er konstruiert die OAuth-Redirect-URI aus der Konstante STRUCTURA_API_BASE:


$cloud_base   = rtrim( STRUCTURA_API_BASE, '/' );
$redirect_uri = $cloud_base . '/channelsOAuthCallback';
 
$result = $this->channels_connections()->init_oauth( $integration_id, $redirect_uri );

Das ist nötig, weil die Cloud-Callback-Funktion ihren eigenen öffentlichen Origin zur Laufzeit nicht kennt. Das Plugin konstruiert die vollständige Callback-URL und übergibt sie der Cloud, die sie im OAuth-State und in der Authorization-URL einbettet.

Gibt { authorizeUrl } zurück — der React-Client leitet den Browser zu dieser URL weiter.

Fehlerbehandlung

Alle Handler folgen demselben Muster:

Service-Methode aufrufen.
Falls das Ergebnis ein WP_Error ist, gib es zurück (WordPress wandelt es automatisch in eine REST-Fehlerantwort um).
Andernfalls in rest_ensure_response() mit dem passenden Statuscode wickeln.

Die Service-Schicht behandelt alle Cloud-Kommunikationsfehler und normalisiert sie auf WP_Error-Instanzen mit beschreibenden Fehlercodes.