Plugin REST API

This is a developer reference. If you’re looking for how to use Structura in wp-admin, start with Dashboard tour — this page is for people writing code against the plugin.

The WordPress plugin exposes REST endpoints under the /structura/v1/channels/ namespace. These are consumed by the React SPA embedded in wp-admin and are usable from any PHP/JS code with WordPress authentication context and the manage_options capability.

Source of truth: plugin/includes/Api/Rest_Api.php.

Endpoints

All routes require manage_options capability.

Handler Patterns

List Connections

Pass-through to the cloud. Returns an array of ConnectionSummary objects. Secrets are never included — the split-doc design in Firestore ensures the client collection is inherently safe.

Save Webhook Connection

Sanitizes inputs (integration_id, webhook_url, display_name, notification_locale, optional connection_id for updates), then forwards to the cloud. The cloud validates the URL via WebhookIntegration.validateTarget() before encrypting and persisting.

Save Credential Connection

Sanitizes the credential key/value map (each key and value through sanitize_text_field), then forwards. The credential shape varies by integration — the plugin doesn’t need per-integration knowledge, as the cloud validates the schema.

Delete Connection

Accepts either a UUID (new connections) or a legacy integration-ID (pre-migration connections). The operation is idempotent — deleting a non-existent connection returns success.

List Events

Unwraps the cloud response and returns the bare event array. Default limit is 25 events, newest first.

List Catalog

Pass-through returning the full marketplace with entitlement annotations (canInstall, blocker per entry).

OAuth Init

The most interesting handler. It constructs the OAuth redirect URI from the STRUCTURA_API_BASE constant:

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

This is necessary because the cloud callback function doesn’t know its own public origin at runtime. The plugin constructs the full callback URL and passes it to the cloud, which embeds it in the OAuth state and the authorization URL.

Returns { authorizeUrl } — the React client redirects the browser to this URL.

Error Handling

All handlers follow the same pattern:

1. Call the service method.
2. If the result is a WP_Error, return it (WordPress converts to a REST error response automatically).
3. Otherwise, wrap in rest_ensure_response() with the appropriate status code.

The service layer handles all cloud communication errors and normalizes them to WP_Error instances with descriptive error codes.