API REST de l’extension

Ceci est une référence pour développeurs. Si vous cherchez comment utiliser Structura dans wp-admin, commencez par Visite du tableau de bord — cette page est pour les gens qui écrivent du code contre l’extension.

L’extension WordPress expose des endpoints REST sous le namespace /structura/v1/channels/. Ils sont consommés par le SPA React intégré dans wp-admin et sont utilisables depuis tout code PHP/JS avec contexte d’authentification WordPress et la capacité manage_options.

Source de vérité : plugin/includes/Api/Rest_Api.php.

Endpoints

Méthode	Route	Handler	Endpoint Cloud
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`

Toutes les routes exigent la capacité manage_options.

Motifs de Handler

List Connections

Pass-through vers le cloud. Renvoie un tableau d’objets ConnectionSummary. Les secrets ne sont jamais inclus — le design split-doc dans Firestore garantit que la collection client est intrinsèquement sûre.

Save Webhook Connection

Sanitise les entrées (integration_id, webhook_url, display_name, notification_locale, optionnel connection_id pour les mises à jour), puis transmet au cloud. Le cloud valide l’URL via WebhookIntegration.validateTarget() avant de chiffrer et persister.

Save Credential Connection

Sanitise la map clé/valeur de l’identifiant (chaque clé et valeur via sanitize_text_field), puis transmet. La forme de l’identifiant varie par intégration — l’extension n’a pas besoin de connaissance par intégration, puisque le cloud valide le schéma.

Delete Connection

Accepte soit un UUID (nouvelles connexions), soit un ID d’intégration legacy (connexions pré-migration). L’opération est idempotente — supprimer une connexion inexistante renvoie un succès.

List Events

Déballe la réponse du cloud et renvoie le tableau brut d’événements. La limite par défaut est de 25 événements, les plus récents en premier.

List Catalog

Pass-through renvoyant le marketplace complet avec annotations de droits (canInstall, blocker par entrée).

OAuth Init

Le handler le plus intéressant. Il construit l’URI de redirection OAuth à partir de la constante STRUCTURA_API_BASE :


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

C’est nécessaire parce que la fonction de callback du cloud ne connaît pas sa propre origine publique à l’exécution. L’extension construit l’URL complète de callback et la passe au cloud, qui l’embarque dans le state OAuth et l’URL d’autorisation.

Renvoie { authorizeUrl } — le client React redirige le navigateur vers cette URL.

Gestion des erreurs

Tous les handlers suivent le même motif :

Appeler la méthode du service.
Si le résultat est un WP_Error, le renvoyer (WordPress le convertit automatiquement en réponse d’erreur REST).
Sinon, envelopper dans rest_ensure_response() avec le code de statut approprié.

La couche service gère toutes les erreurs de communication avec le cloud et les normalise en instances de WP_Error avec des codes d’erreur descriptifs.