WordPress sait depuis longtemps exposer des données avec la REST API. L’Abilities API ajoute une couche différente : un registre standardisé d’actions qu’un thème, un plugin ou un système externe peut découvrir et exécuter. Une « ability » décrit une capacité précise, ses entrées, sa sortie et les droits nécessaires.
Disponible à partir de WordPress 6.9, cette API intéresse directement les développeurs qui connectent des agents IA ou des automatisations. Elle évite de transformer chaque intégration en collection d’endpoints et de conventions propriétaires.
Une ability n’est pas un simple endpoint
Une ability porte un nom unique au format namespace/action, un libellé, une description, une catégorie et des schémas d’entrée et de sortie. Son exécution est reliée à un callback PHP. Ce contrat rend la fonctionnalité découvrable sans obliger le consommateur à connaître l’implémentation interne du plugin.
Par exemple, acme/get-order-summary peut accepter un identifiant de commande et renvoyer un objet structuré. Le contrat doit rester étroit : une action qui « gère toute la boutique » sera difficile à autoriser, tester et maintenir.
Décrire les entrées et sorties avec JSON Schema
Un agent est plus fiable lorsqu’il reçoit un contrat explicite. Définissez les types, champs obligatoires, formats, bornes et valeurs autorisées. La description humaine explique l’intention ; le schéma empêche une partie des appels ambigus.
Le schéma de sortie est tout aussi important. Il permet au client de savoir s’il recevra une liste, un objet métier ou un simple statut. Une réponse stable facilite les tests de contrat et limite les adaptations fragiles dans les prompts.
Appliquer les permissions côté serveur
La décision d’autorisation ne doit jamais être déléguée au modèle. Chaque ability possède une fonction de permission qui doit vérifier l’utilisateur courant et la capacité WordPress adaptée. La validation doit être refaite à chaque exécution, même si l’interface cliente masque déjà l’action.
Séparez les capacités de lecture et d’écriture. Une ability de consultation peut être marquée comme non destructive, tandis qu’une action qui modifie un article, un compte ou une commande doit annoncer clairement son effet et exiger un droit plus fort.
Choisir explicitement l’exposition REST
Une ability n’est pas exposée par défaut dans l’API REST. Le paramètre show_in_rest doit être activé intentionnellement. Cette valeur est un garde-fou utile : une fonctionnalité interne au site n’a aucune raison de devenir automatiquement appelable depuis l’extérieur.
Les endpoints REST des abilities nécessitent un utilisateur authentifié. Les mots de passe d’application WordPress conviennent à certains usages serveur à serveur, à condition de les limiter, de les stocker hors du dépôt et de prévoir leur rotation.
Concevoir des actions sûres pour un agent
Une bonne ability est petite, déterministe autant que possible et idempotente lorsque le métier le permet. Préférez preview-invoice puis send-invoice à une action unique qui calcule et envoie immédiatement. Le premier appel produit un aperçu vérifiable ; le second réalise l’effet après confirmation.
Ajoutez des limites de volume, des délais d’expiration et des identifiants d’idempotence aux opérations sensibles. Journalisez l’utilisateur, l’ability, le résultat et la durée, mais évitez de conserver les données personnelles ou les secrets dans les traces.
Tester le contrat, pas seulement le callback
Les tests doivent couvrir le succès, les entrées invalides, l’absence de permission et les erreurs métier. Vérifiez également que les actions non exposées restent absentes du catalogue REST et qu’une modification de schéma ne casse pas les consommateurs existants.
Cette démarche complète l’audit de sécurité d’un plugin WordPress avec l’IA. L’agent peut aider à générer les cas de test, mais la frontière d’autorisation reste une décision d’architecture.
Quand utiliser l’Abilities API
- Pour publier un catalogue de fonctions métier cohérent entre plusieurs plugins.
- Pour permettre à une automatisation de découvrir les actions disponibles.
- Pour fournir à un agent des outils structurés et limités.
- Pour unifier l’exécution interne, REST et WP-CLI autour du même contrat.
Un endpoint REST classique reste pertinent pour une ressource publique ou une API déjà versionnée. L’Abilities API apporte surtout de la valeur lorsque l’action métier, sa découvrabilité et ses permissions sont au centre du besoin.
Checklist d’implémentation
- Nom d’ability stable et spécifique.
- Schémas d’entrée et de sortie complets.
- Permission contrôlée côté serveur.
- Lecture et écriture séparées.
show_in_restactivé uniquement si nécessaire.- Effets destructifs signalés et confirmables.
- Tests de contrat et journalisation sans données sensibles.
