# Abilities API de WordPress 6.9 : exposer les capacités d’une extension

> Une nouvelle API core standardise la déclaration de « capacités » métier invocables par un agent externe. Voici comment l'adopter dans une extension avant la sortie officielle en 6.9.

- Auteur : Clément Hadrot
- Publié le : 2025-09-20
- Mis à jour le : 2025-09-20
- Catégorie : Extensions
- URL : https://wpmoderne.dev.wordpress-developpement.fr/extensions/abilities-api-wordpress-6-9-declarer-capacite/

## L’essentiel

- wp_register_ability() déclare une capacité avec un schéma d'entrée et de sortie
- La capacité reste indépendante du protocole d'invocation (MCP ou autre)
- Adopter tôt via le plugin de fonctionnalité facilite la migration en 6.9

`wp_register_ability( 'wpm-billing/generate-invoice', $args )` : cette seule ligne suffit, une fois le feature plugin Abilities API activé, à rendre une action métier d'une extension de facturation invocable par un système externe standardisé. WordPress 6.9, attendu en décembre 2025, doit intégrer cette API au cœur — mais elle est disponible dès aujourd'hui via le plugin de fonctionnalité officiel du groupe de travail Core.

L'idée derrière cette API : donner un vocabulaire commun aux extensions pour décrire « ce qu'elles savent faire », indépendamment du protocole qui viendra ensuite consommer cette description (le MCP Adapter, distinct et traité séparément, en est un exemple, mais pas le seul possible).

## Le principe : une capacité, pas un simple hook

Une capacité (« ability ») se distingue d'une action ou d'un filtre classique par trois éléments obligatoires : un identifiant unique préfixé par le nom de l'extension, un schéma décrivant les entrées attendues, et un schéma décrivant la sortie produite. C'est cette structure qui permet à un système tiers de découvrir dynamiquement ce qu'une extension propose, sans documentation manuelle à tenir à jour.

```
add_action( 'abilities_api_init', function () {
    wp_register_ability( 'wpm-billing/generate-invoice', array(
        'label'               => __( 'Générer une facture', 'wpm-billing' ),
        'description'         => __( 'Crée une facture PDF pour une commande donnée.', 'wpm-billing' ),
        'input_schema'        => array(
            'type'       => 'object',
            'properties' => array(
                'order_id' => array( 'type' => 'integer' ),
            ),
            'required'   => array( 'order_id' ),
        ),
        'output_schema'       => array(
            'type'       => 'object',
            'properties' => array(
                'invoice_url' => array( 'type' => 'string' ),
            ),
        ),
        'execute_callback'    => 'wpm_billing_generate_invoice',
        'permission_callback' => function () {
            return current_user_can( 'manage_woocommerce' );
        },
    ) );
} );
```

## Pourquoi ne pas simplement exposer un endpoint REST existant

> L'essentiel à retenir : wp_register_ability() déclare une capacité avec un schéma d'entrée et de sortie ; La capacité reste indépendante du protocole d'invocation (MCP ou autre) ; Adopter tôt via le plugin de fonctionnalité facilite la migration en 6.9

La tentation est grande de considérer l'Abilities API comme une simple couche de documentation par-dessus une route REST déjà en place. Ce serait manquer l'essentiel : le `permission_callback` d'une capacité est évalué indépendamment du système d'authentification REST, ce qui permet à un agent conversationnel authentifié autrement (jeton applicatif, session interne) d'invoquer la capacité sans transiter par toute la pile REST.

## Étape par étape : déclarer une première capacité

1. Vérifier la présence du feature plugin Abilities API (ou du support natif, une fois 6.9 sortie) avant d'enregistrer quoi que ce soit, via `function_exists( 'wp_register_ability' )`.
2. Choisir un identifiant stable, préfixé, qui ne changera plus une fois publié — un agent externe pourrait en dépendre.
3. Écrire des schémas JSON précis : un type `integer` mal déclaré en `string` provoque des erreurs de validation silencieuses côté consommateur.
4. Isoler la logique métier dans une fonction réutilisable, appelée aussi bien par la capacité que par l'interface d'administration classique.
5. Tester l'invocation via `wp_get_ability( 'wpm-billing/generate-invoice' )->execute( $input )` avant de brancher un quelconque protocole externe.

## Ce qui reste incertain avant la sortie de 6.9

Le feature plugin évolue encore sur des points non stabilisés : la gestion fine des espaces de noms pour les grandes extensions à plusieurs modules, et la manière dont les capacités seront listées dans l'écran Site Health. Il est raisonnable d'adopter l'API dès maintenant pour les projets internes, tout en évitant de la documenter publiquement comme une fonctionnalité finale tant que le cœur ne l'a pas intégrée.

> Traitez chaque capacité comme une API publique dès le premier jour : un identifiant renommé après coup casse tout consommateur externe, agent IA ou script.

## Pour aller plus loin

L'Abilities API ne remplace ni les hooks, ni la REST API : elle ajoute une couche de description structurée par-dessus la logique déjà existante. Une extension qui expose déjà proprement ses fonctions métier dans des classes de service n'aura, la plupart du temps, qu'à écrire les schémas d'entrée et de sortie — le vrai travail de conception a déjà été fait en amont.