WordPress Abilities API : guide développeur

Introduction

Avec la sortie de WordPress 6.9 “Gene” en décembre 2025, l’écosystème WordPress franchit une étape majeure dans son évolution. Parmi les nombreuses nouveautés de cette version, l’Abilities API se distingue comme l’une des fonctionnalités les plus prometteuses pour les développeurs. Cette nouvelle API ouvre la voie à une intégration native avec les systèmes d’intelligence artificielle et révolutionne la façon dont les plugins, thèmes et le cœur de WordPress exposent leurs fonctionnalités.

L’Abilities API n’est pas simplement une nouvelle couche d’abstraction. Elle représente un changement de paradigme dans la conception des extensions WordPress. Désormais, chaque fonctionnalité peut être déclarée de manière standardisée, documentée automatiquement et rendue accessible à des systèmes externes, qu’il s’agisse d’outils d’automatisation ou d’agents IA conversationnels.

Dans ce guide complet, nous allons explorer en profondeur cette nouvelle API : ses concepts fondamentaux, son implémentation pratique et son intégration avec le protocole Model Context Protocol (MCP). Que vous soyez développeur de plugins ou intégrateur WordPress, vous découvrirez comment tirer parti de cette technologie pour créer des solutions plus intelligentes et interconnectées.

Qu’est-ce que l’Abilities API ?

Définition et concepts clés

L’Abilities API est un système de registre centralisé qui permet d’enregistrer et de découvrir des unités de fonctionnalité distinctes au sein d’un site WordPress. Concrètement, une Ability (ou “capacité” en français) représente une action ou une fonctionnalité spécifique que votre site peut accomplir.

Chaque Ability est caractérisée par plusieurs éléments essentiels :

Un nom unique suivant le format namespace/ability-name
Un label et une description lisibles par les humains
Un schéma d’entrée définissant les paramètres attendus (format JSON Schema)
Un schéma de sortie décrivant la structure du résultat retourné
Une catégorie pour organiser les abilities connexes
Un callback d’exécution qui contient la logique métier
Un callback de permission pour contrôler l’accès

Cette structure rigoureuse offre plusieurs avantages majeurs. Elle permet une validation automatique des données, une documentation autogénérée et une interopérabilité native avec des systèmes externes.

Architecture du système

L’Abilities API repose sur deux classes centrales qui fonctionnent comme des registres singleton :

WP_Abilities_Registry gère l’ensemble des abilities enregistrées. Ce registre fournit des méthodes pour ajouter, supprimer, rechercher et interroger les abilities disponibles sur le site.

WP_Abilities_Category_Registry organise les abilities en catégories logiques. Chaque ability doit appartenir à exactement une catégorie, ce qui facilite la navigation et la découverte des fonctionnalités.

Cette architecture garantit une cohérence dans tout l’écosystème. Que vous développiez un plugin e-commerce, un outil de SEO ou une extension de sécurité, vous utilisez les mêmes conventions et les mêmes mécanismes pour exposer vos fonctionnalités.

Objectifs de conception

L’équipe WordPress Core AI a défini quatre objectifs principaux lors de la conception de cette API :

Découvrabilité : Toutes les abilities peuvent être listées, interrogées et inspectées via des interfaces standardisées.
Interopérabilité : Un schéma uniforme permet à différents composants de fonctionner ensemble de manière transparente.
Sécurité prioritaire : Des contrôles de permission explicites déterminent qui peut invoquer chaque ability.
Adoption progressive : L’API est disponible comme package Composer avant son intégration dans le cœur de WordPress.

Pourquoi utiliser l’Abilities API ?

Les limitations de l’approche traditionnelle

Avant l’Abilities API, les développeurs WordPress devaient créer manuellement des endpoints REST, des shortcodes, des hooks et des fonctions pour exposer leurs fonctionnalités. Cette approche fragmentée posait plusieurs problèmes :

Manque de standardisation : Chaque plugin définissait ses propres conventions
Documentation manuelle : Les développeurs devaient documenter chaque API séparément
Validation ad hoc : La vérification des entrées/sorties était laissée à la discrétion de chacun
Découverte difficile : Aucun moyen centralisé de connaître les fonctionnalités d’un site

L’Abilities API résout ces problèmes en proposant un cadre unifié et cohérent.

Avantages pour les développeurs

Standardisation du code : En adoptant l’Abilities API, vous suivez des conventions établies. Votre code devient plus lisible et maintenable. Les autres développeurs comprennent immédiatement la structure de vos fonctionnalités.

Validation automatique : Les schémas JSON assurent que les données entrantes et sortantes respectent le format attendu. Plus besoin d’écrire des validations manuelles répétitives.

Documentation intégrée : Chaque ability s’autodocumente grâce à ses labels, descriptions et schémas. Les outils peuvent générer automatiquement une documentation technique.

Exposition multicanale : Une ability enregistrée peut être appelée depuis PHP, JavaScript ou l’API REST sans code supplémentaire.

Cas d’usage concrets

L’Abilities API trouve sa place dans de nombreux scénarios :

Plugins de contenu : Exposer des fonctions de création, modification et suppression d’articles
Extensions e-commerce : Rendre accessibles les opérations de gestion de produits et commandes
Outils de SEO : Permettre l’analyse et l’optimisation automatisées du contenu
Systèmes de formulaires : Automatiser le traitement et l’export des soumissions
Intégrations tierces : Connecter WordPress à des services externes de manière standardisée

Comment enregistrer une Ability

Étape 1 : Enregistrer une catégorie

Avant de créer une ability, vous devez définir la catégorie à laquelle elle appartiendra. Les catégories organisent les abilities de manière logique et facilitent leur découverte.

Utilisez le hook wp_abilities_api_categories_init pour enregistrer vos catégories :

add_action( 'wp_abilities_api_categories_init', 'mon_plugin_register_categories' );

function mon_plugin_register_categories(): void {
    wp_register_ability_category(
        'gestion-contenu',
        array(
            'label'       => __( 'Gestion de Contenu', 'mon-plugin' ),
            'description' => __( 'Abilities pour créer, modifier et gérer le contenu du site.', 'mon-plugin' ),
        )
    );
}

Le slug de catégorie doit être unique et utiliser uniquement des caractères alphanumériques minuscules et des tirets.

Étape 2 : Définir le schéma d’entrée

Le schéma d’entrée (input_schema) décrit les paramètres que votre ability accepte. WordPress implémente un validateur basé sur la spécification JSON Schema Version 4.

Voici un exemple de schéma pour une ability d’analyse de texte :

'input_schema' => array(
    'type'       => 'object',
    'properties' => array(
        'texte' => array(
            'type'        => 'string',
            'description' => __( 'Le texte à analyser.', 'mon-plugin' ),
            'minLength'   => 10,
            'maxLength'   => 5000,
        ),
        'langue' => array(
            'type'        => 'string',
            'description' => __( 'Code de langue ISO 639-1.', 'mon-plugin' ),
            'enum'        => array( 'fr', 'en', 'es', 'de' ),
            'default'     => 'fr',
        ),
    ),
    'required' => array( 'texte' ),
),

Étape 3 : Définir le schéma de sortie

Le schéma de sortie (output_schema) décrit la structure du résultat retourné par votre ability :

'output_schema' => array(
    'type'       => 'object',
    'properties' => array(
        'sentiment' => array(
            'type'        => 'string',
            'description' => __( 'Résultat de l\'analyse de sentiment.', 'mon-plugin' ),
            'enum'        => array( 'positif', 'négatif', 'neutre' ),
        ),
        'score' => array(
            'type'        => 'number',
            'description' => __( 'Score de confiance entre 0 et 1.', 'mon-plugin' ),
            'minimum'     => 0,
            'maximum'     => 1,
        ),
        'mots_cles' => array(
            'type'        => 'array',
            'items'       => array( 'type' => 'string' ),
            'description' => __( 'Liste des mots-clés extraits.', 'mon-plugin' ),
        ),
    ),
),

Étape 4 : Créer le callback d’exécution

Le callback d’exécution contient la logique métier de votre ability. Il reçoit les paramètres d’entrée validés et doit retourner un résultat conforme au schéma de sortie :

function mon_plugin_analyser_texte( array $input ): array {
    $texte  = $input['texte'];
    $langue = $input['langue'] ?? 'fr';

    // Logique d'analyse (exemple simplifié)
    $mots      = str_word_count( $texte, 1 );
    $mots_cles = array_unique( array_filter( $mots, function( $mot ) {
        return strlen( $mot ) > 5;
    } ) );

    // Analyse de sentiment fictive
    $sentiment = 'neutre';
    $score     = 0.5;

    if ( preg_match( '/excellent|parfait|génial|super/i', $texte ) ) {
        $sentiment = 'positif';
        $score     = 0.85;
    } elseif ( preg_match( '/mauvais|terrible|nul|décevant/i', $texte ) ) {
        $sentiment = 'négatif';
        $score     = 0.75;
    }

    return array(
        'sentiment' => $sentiment,
        'score'     => $score,
        'mots_cles' => array_values( array_slice( $mots_cles, 0, 10 ) ),
    );
}

Étape 5 : Enregistrer l’ability complète

Assemblez tous les éléments pour enregistrer votre ability :

add_action( 'wp_abilities_api_init', 'mon_plugin_register_abilities' );

function mon_plugin_register_abilities(): void {
    wp_register_ability(
        'mon-plugin/analyser-texte',
        array(
            'label'       => __( 'Analyser un Texte', 'mon-plugin' ),
            'description' => __( 'Analyse le sentiment et extrait les mots-clés d\'un texte.', 'mon-plugin' ),
            'category'    => 'gestion-contenu',
            'input_schema' => array(
                'type'       => 'object',
                'properties' => array(
                    'texte' => array(
                        'type'        => 'string',
                        'description' => __( 'Le texte à analyser.', 'mon-plugin' ),
                        'minLength'   => 10,
                    ),
                    'langue' => array(
                        'type'    => 'string',
                        'enum'    => array( 'fr', 'en', 'es', 'de' ),
                        'default' => 'fr',
                    ),
                ),
                'required' => array( 'texte' ),
            ),
            'output_schema' => array(
                'type'       => 'object',
                'properties' => array(
                    'sentiment' => array(
                        'type' => 'string',
                        'enum' => array( 'positif', 'négatif', 'neutre' ),
                    ),
                    'score' => array(
                        'type'    => 'number',
                        'minimum' => 0,
                        'maximum' => 1,
                    ),
                    'mots_cles' => array(
                        'type'  => 'array',
                        'items' => array( 'type' => 'string' ),
                    ),
                ),
            ),
            'execute_callback'    => 'mon_plugin_analyser_texte',
            'permission_callback' => function() {
                return current_user_can( 'edit_posts' );
            },
            'meta' => array(
                'show_in_rest' => true,
            ),
        )
    );
}

Les endpoints REST API

Vue d’ensemble des routes disponibles

Lorsque vous activez l’option show_in_rest, vos abilities deviennent accessibles via l’API REST sous le namespace wp-abilities/v1. Voici les endpoints disponibles :

Route	Méthode	Description
`/wp-abilities/v1/abilities`	GET	Liste toutes les abilities
`/wp-abilities/v1/abilities/{name}`	GET	Récupère une ability spécifique
`/wp-abilities/v1/abilities/{name}/run`	GET/POST/DELETE	Exécute une ability
`/wp-abilities/v1/categories`	GET	Liste toutes les catégories
`/wp-abilities/v1/categories/{slug}`	GET	Récupère une catégorie spécifique

Authentification requise

L’accès aux endpoints de l’Abilities API nécessite une authentification. WordPress supporte plusieurs méthodes :

Cookies d’authentification : Pour les appels depuis le navigateur
Application Passwords : Recommandé pour les accès externes
Plugins d’authentification : OAuth, JWT, etc.

Exécuter une ability via REST

Pour exécuter une ability, envoyez une requête vers l’endpoint /run :

# Avec curl et Application Password
curl -X POST \
  https://monsite.com/wp-json/wp-abilities/v1/abilities/mon-plugin/analyser-texte/run \
  -H "Authorization: Basic $(echo -n 'utilisateur:mot_de_passe_application' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"texte": "Cet article WordPress est vraiment excellent et très utile."}'

La réponse sera conforme au schéma de sortie défini :

{
  "sentiment": "positif",
  "score": 0.85,
  "mots_cles": ["article", "WordPress", "vraiment", "excellent"]
}

Gestion des erreurs

L’API retourne des codes d’erreur standardisés :

ability_invalid_permissions : L’utilisateur n’a pas les droits requis
ability_invalid_input : Les données d’entrée ne respectent pas le schéma
ability_not_found : L’ability demandée n’existe pas
ability_execution_error : Une erreur s’est produite lors de l’exécution

Intégration avec l’IA et le protocole MCP

Le Model Context Protocol (MCP)

Le Model Context Protocol est un standard ouvert créé par Anthropic (les créateurs de Claude) et adopté par OpenAI, Google DeepMind et d’autres leaders de l’IA. Ce protocole fournit un moyen universel pour les assistants IA de se connecter à des outils externes, des sources de données et des workflows.

L’équipe WordPress a développé un MCP Adapter qui fait le pont entre l’Abilities API et le protocole MCP. Cette intégration permet aux agents IA de découvrir et d’exécuter les fonctionnalités de votre site WordPress de manière conversationnelle.

Installation du MCP Adapter

Le MCP Adapter est disponible comme plugin WordPress ou package Composer :

# Via Composer
composer require wordpress/mcp-adapter

# Ou téléchargez le plugin depuis
# https://github.com/WordPress/mcp-adapter/releases

Une fois installé, l’adapter expose automatiquement vos abilities enregistrées aux clients MCP.

Fonctionnement de l’intégration

Le MCP Adapter :

Convertit les abilities WordPress en outils MCP (tools, resources, prompts)
Respecte les callbacks de permission définis dans vos abilities
Supporte les transports HTTP et STDIO
Permet la création de plusieurs serveurs MCP avec des configurations différentes

Cette architecture garantit que les agents IA ne peuvent exécuter que les actions pour lesquelles l’utilisateur est autorisé.

Cas d’usage avec l’IA

L’intégration Abilities API + MCP ouvre des possibilités puissantes :

Gestion conversationnelle : “Crée un nouvel article sur les tendances SEO 2026”
Automatisation intelligente : Un agent IA peut enchaîner plusieurs abilities pour accomplir des tâches complexes
Analyse de données : “Analyse les performances de mes 10 derniers articles”
Workflows cross-systèmes : Connecter WordPress à d’autres outils via des agents IA unifiés

Exemple de configuration MCP

Pour exposer une ability à un agent IA Claude via le MCP Adapter, aucune configuration supplémentaire n’est nécessaire si show_in_rest est activé. L’adapter détecte automatiquement les abilities disponibles et les rend accessibles.

Bonnes pratiques et erreurs à éviter

Conventions de nommage

Respectez toujours le format namespace/ability-name pour vos abilities. Le namespace devrait correspondre au slug de votre plugin ou thème. Utilisez uniquement des caractères alphanumériques minuscules, des tirets et des slashes.

Bon : mon-plugin/creer-article, theme-pro/generer-sitemap

Mauvais : CreateArticle, mon_plugin_ability, MonPlugin/Action

Sécurité des permissions

Définissez toujours un permission_callback explicite. Ne vous contentez pas de retourner true. Utilisez les capabilities WordPress existantes comme edit_posts, manage_options, etc.

// Bon
'permission_callback' => function() {
    return current_user_can( 'edit_posts' );
},

// Mauvais - ne faites jamais ça
'permission_callback' => '__return_true',

Schémas complets

Définissez des schémas d’entrée et de sortie détaillés. Plus vos schémas sont précis, meilleure sera la validation automatique et la documentation générée.

Incluez systématiquement :

Les types de données (string, number, array, object)
Les descriptions explicatives
Les contraintes (minLength, maximum, enum, etc.)
Les champs requis

Gestion des erreurs dans les callbacks

Votre callback d’exécution doit gérer les erreurs proprement. Retournez un WP_Error en cas de problème :

function mon_callback( array $input ): array|WP_Error {
    try {
        // Logique métier
        $resultat = effectuer_operation( $input );
        return $resultat;
    } catch ( Exception $e ) {
        return new WP_Error(
            'execution_failed',
            $e->getMessage(),
            array( 'status' => 500 )
        );
    }
}

Performance et mise en cache

Pour les abilities qui effectuent des opérations coûteuses, implémentez une stratégie de cache :

function mon_ability_avec_cache( array $input ): array {
    $cache_key = 'ability_result_' . md5( wp_json_encode( $input ) );
    $cached    = wp_cache_get( $cache_key, 'abilities' );

    if ( false !== $cached ) {
        return $cached;
    }

    $resultat = effectuer_operation_couteuse( $input );
    wp_cache_set( $cache_key, $resultat, 'abilities', HOUR_IN_SECONDS );

    return $resultat;
}

Conclusion

L’Abilities API représente une avancée majeure dans l’écosystème WordPress. En standardisant la façon dont les fonctionnalités sont déclarées et exposées, cette API facilite la création de plugins plus interopérables, mieux documentés et prêts pour l’ère de l’intelligence artificielle.

L’intégration native avec le protocole MCP ouvre des perspectives passionnantes. Les sites WordPress peuvent désormais interagir avec des agents IA conversationnels, automatiser des workflows complexes et s’intégrer de façon fluide dans des écosystèmes multi-outils.

Pour les développeurs, l’adoption de l’Abilities API n’est plus optionnelle mais essentielle. Les utilisateurs attendent des plugins qui fonctionnent de manière cohérente et qui peuvent être pilotés par des assistants IA. En maîtrisant cette technologie dès aujourd’hui, vous positionnez vos projets pour le futur de WordPress.

Prêt à intégrer l’Abilities API dans vos plugins ? L’équipe Partikuls peut vous accompagner dans cette transition et vous aider à créer des solutions WordPress intelligentes et connectées. Contactez-nous pour discuter de votre projet.

WordPress Abilities API : le guide complet pour développeurs