# Notre grille avant d’adopter une API expérimentale de blocs

> Après avoir été échaudés par une API marquée __experimental retirée sans préavis, voici les critères de maturité qu'une agence prudente retient avant d'intégrer un client.

- Auteur : Clément Hadrot
- Publié le : 2025-06-30
- Mis à jour le : 2025-06-30
- Catégorie : Blocs Gutenberg
- URL : https://wpmoderne.dev.wordpress-developpement.fr/blocs/grille-adoption-api-experimentale-blocs/

## L’essentiel

- Une API __experimental peut disparaître sans cycle de dépréciation
- Vérifier le nombre de versions où elle est restée stable
- Toujours prévoir un plan B avant de livrer un client dessus

Il y a deux ans, un bloc client de Kaolin reposait sur un composant marqué `__experimentalToolsPanel`, alors seule façon élégante de regrouper des contrôles d'inspecteur en accordéon. Une mise à jour mineure de Gutenberg a renommé l'API, changé sa signature, et cassé le bloc en production du jour au lendemain, sans ligne dans le changelog assez explicite pour l'anticiper. Depuis, l'agence applique une grille de décision avant tout usage d'une API préfixée `__experimental` ou `unstable` sur un projet client facturé.

## Ce que signifie réellement le préfixe __experimental

Une API marquée ainsi dans le cœur de WordPress ou dans les paquets `@wordpress/*` n'offre aucune garantie de stabilité entre deux versions mineures, contrairement aux API stables qui suivent un cycle de dépréciation avec avertissement avant suppression. Elle peut être renommée, restructurée ou retirée sans préavis formel, précisément parce qu'elle sert à faire mûrir une fonctionnalité en conditions réelles avant sa stabilisation éventuelle.

## Les critères retenus avant d'intégrer une telle API sur un projet facturé

### Ancienneté et stabilité observée

Une API expérimentale apparue dans la dernière version mineure en date est écartée par défaut. L'équipe attend qu'elle traverse au moins trois versions mineures consécutives sans changement de signature avant de l'envisager, ce qui donne une indication (jamais une garantie) de maturité relative.

### Présence dans le cœur ou dans un paquet isolé

Une API expérimentale utilisée massivement par l'éditeur de blocs lui-même (visible dans le code source de Gutenberg pour ses propres composants natifs) a statistiquement moins de risque de disparaître brutalement qu'une API expérimentale isolée, peu utilisée en interne par l'équipe qui la maintient.

### Existence d'un plan de repli

Avant toute intégration, l'équipe documente explicitement ce qui remplacerait l'API en cas de retrait : une réimplémentation maison du même comportement, plus verbeuse mais stable, ou un renoncement pur et simple à la fonctionnalité visuelle concernée.

> L'essentiel à retenir : Une API __experimental peut disparaître sans cycle de dépréciation ; Vérifier le nombre de versions où elle est restée stable ; Toujours prévoir un plan B avant de livrer un client dessus

## La grille sous forme de tableau

| Critère | Question posée | Seuil retenu |
| --- | --- | --- |
| Ancienneté | Depuis combien de versions mineures l'API est-elle inchangée ? | Trois versions minimum |
| Usage interne | Le cœur de Gutenberg l'utilise-t-il lui-même massivement ? | Oui, de préférence |
| Plan de repli | Que fait-on si elle disparaît la semaine prochaine ? | Documenté avant intégration |
| Criticité du projet | Le client peut-il tolérer un correctif d'urgence si l'API casse ? | Contrat de maintenance actif requis |

## Un exemple concret d'application de la grille

Lorsqu'un développeur a proposé d'utiliser une API expérimentale de gestion de styles de bloc pour un client sans contrat de maintenance actif, la grille a permis de refuser la proposition sans discussion houleuse : le dernier critère, l'absence de contrat de maintenance, suffisait à lui seul à écarter l'option, quel que soit par ailleurs le niveau de maturité de l'API en question.

- Ne jamais présenter à un client un délai basé sur une API expérimentale sans mentionner explicitement ce risque dans le devis.
- Revoir la grille à chaque montée de version majeure de WordPress, une API jugée stable pouvant redevenir instable si son paquet est réécrit.
- Documenter systématiquement, dans le code lui-même, un commentaire signalant l'usage d'une API expérimentale et sa date d'évaluation.

> Une API expérimentale n'est pas interdite, elle est simplement empruntée : il faut toujours savoir ce qu'on fera le jour où on doit la rendre.

## Notre verdict

Cette grille n'élimine pas le risque, elle le rend explicite et partagé avant la décision, plutôt que découvert a posteriori lors d'un incident de production. Depuis sa mise en place, aucune API expérimentale intégrée par Kaolin n'a cassé de projet client sans qu'un plan de repli documenté existe déjà.