Comment documenter une API REST WordPress avec l’IA

L’IA peut rédiger une documentation d’API REST WordPress à partir des routes, schémas et tests enregistrés, mais elle ne doit pas inventer de points de terminaison, de permissions, d’effets de bord ou d’exemples qui n’ont pas été vérifiés par rapport à l’implémentation en cours d’exécution.

L’IA est surtout utile ici comme organisatrice de preuves, moteur de comparaison et assistante de rédaction. Elle peut rendre une tâche WordPress complexe plus facile à examiner, mais elle ne peut pas créer une autorité manquante, certifier des faits qu’elle n’a pas observés ou convertir silencieusement une recommandation en permission d’agir.

En une phrase : l’IA peut rédiger une documentation d’API REST WordPress à partir des routes, schémas et tests enregistrés, mais elle ne doit pas inventer de points de terminaison, de permissions, d’effets de bord ou d’exemples qui n’ont pas été vérifiés par rapport à l’implémentation en cours d’exécution.

Ce que ce guide vous aide à accomplir

Créez une documentation d’API versionnée et étayée par des preuves qui décrit les routes, méthodes, authentifications, callbacks de permissions, schémas, effets de bord, erreurs et exemples testés.

• Un inventaire des routes et méthodes lié aux preuves du code source et de l’exécution.
• Des schémas de requête et de réponse avec champs requis, conditionnels et en lecture seule.
• Le comportement d’authentification et d’autorisation, y compris les refus attendus.
• Des exemples testés, cas d’erreur, notes de version et statut de dépréciation.

L’artefact final doit être compréhensible par la personne responsable de la décision et reproductible par quelqu’un qui n’a pas participé au prompt d’origine. Une réponse fluide ne suffit pas. Chaque conclusion importante doit avoir une source, un périmètre et un parcours de vérification. Lorsque les preuves ne permettent pas d’établir quelque chose, la sortie correcte est un inconnu explicite ou une hypothèse vérifiable.

Preuves et entrées à préparer

• La sortie des routes enregistrées depuis l’environnement visé.
• Le code source du contrôleur et des callbacks à un commit exact.
• Les schémas, callbacks de permissions et exigences de capacités.
• Les tests d’intégration et les fixtures requête-réponse expurgées.
• La politique de versionnage, de dépréciation et de compatibilité ascendante.

Avant de fournir des preuves à un assistant, retirez les identifiants, valeurs secrètes et renseignements personnels sans rapport. Préservez les identifiants, versions, horodatages, paramètres régionaux, unités et étiquettes de source nécessaires pour interpréter ce qui reste. Une capture d’écran sans URL, état ou date peut être un contexte utile, mais constitue rarement une autorité suffisante pour une décision de production.

Ne commencez pas par une demande générale telle que « examinez ceci », « corrigez ceci » ou « améliorez ceci ». Définissez la décision que le travail doit appuyer, la population incluse, la source qui fait autorité pour chaque champ, les opérations permises et les actions qui demeurent interdites. Un accès WordPress authentifié ou une exportation contrôlée est requis pour cette tâche.

La découverte et la documentation sont différentes

Une route peut être enregistrée sans schéma complet, exemples utiles ou documentation claire des effets de bord. La découverte à l’exécution est une entrée, pas la référence terminée.

L’authentification n’est pas l’autorisation

Un mot de passe d’application valide identifie un utilisateur ; chaque point de terminaison nécessite toujours une décision de permission appropriée à l’action et à l’objet.

Les exemples sont des affirmations exécutables

Une requête copiée implique que la méthode, le chemin, les champs et la réponse sont actuels. Les exemples devraient être générés depuis des tests ou vérifiés par eux.

Garder l’observation, l’inférence et l’autorité séparées

Un examen contrôlé devrait distinguer au moins quatre états :

1. Observé : présent directement dans un enregistrement, fichier, réponse, page rendue ou test exécuté nommé.
2. Inféré : une interprétation plausible soutenue par des preuves, mais non établie directement.
3. Recommandé : une décision humaine proposée ou une action suivante.
4. Autorisé et vérifié : une modification approuvée séparément, exécutée puis vérifiée selon les critères d’acceptation.

La sortie de l’IA commence habituellement dans les trois premiers états. Elle ne devient pas autorisée uniquement parce qu’elle est détaillée, cohérente à l’interne ou techniquement convaincante. Préservez cette distinction dans les tableaux, rapports, tickets et études de cas publiques.

Un flux de travail sûr

1. Figer la version du plugin ou de l’application et l’environnement cible.
2. Recueillir la découverte des routes, les définitions sources, les schémas et les tests.
3. Normaliser les points de terminaison par espace de noms, chemin, méthode et version.
4. Demander à l’IA de rédiger la documentation avec des références de preuve explicites et les inconnus.
5. Vérifier chaque affirmation relative à l’authentification, aux permissions, à la validation et aux effets de bord.
6. Exécuter les exemples sur une fixture isolée et expurger les valeurs sensibles.
7. Examiner l’utilisabilité pour les développeurs, le guide des erreurs et la compatibilité ascendante.
8. Publier la référence versionnée et la retester dans la CI de publication.

Cette séquence place délibérément un examen responsable entre l’analyse et l’implémentation. Si une étape ultérieure nécessite un accès plus large, créez une nouvelle tâche, une nouvelle identité ou une modification explicite des permissions. N’élevez pas silencieusement l’identité analytique parce qu’elle a atteint une frontière correcte.

Recette de prompt

Remplacez chaque valeur entre crochets avant d’utiliser le prompt. Ne collez pas de mots de passe, clés API, témoins d’authentification, dossiers privés de clients ou renseignements personnels sans rapport.

Vous examinez [TASK SCOPE] pour [SITE, REPOSITORY OR DATASET] en utilisant uniquement les preuves fournies.

Objectif :
Créez une documentation d’API versionnée et étayée par des preuves qui décrit les routes, méthodes, authentifications, callbacks de permissions, schémas, effets de bord, erreurs et exemples testés.

Retournez les champs suivants :
- Espace de noms
- Route
- Méthode
- Objectif
- Authentification
- Permission
- Arguments
- Schéma
- Effet de bord
- Réponse de succès
- Réponse d’erreur
- Fixture de test
- Version

Règles :
1. N’inventez pas de routes, champs, capacités ou codes d’état.
2. Séparez l’authentification de l’autorisation du point de terminaison.
3. Préservez exactement les tokens d’espace de noms, de méthode, de champ et d’énumération.
4. Utilisez des exemples expurgés générés à partir de fixtures sûres.
5. N’appelez pas de points de terminaison d’écriture de production.

Pour chaque constat :
- identifiez la source, l’enregistrement, l’URL, le fichier, la ligne, l’ID d’objet, l’état ou la ligne du jeu de données exacts ;
- préservez les dates, versions, unités, paramètres régionaux, identifiants et dénominateurs ;
- séparez l’observation, l’inférence, la recommandation et l’inconnu ;
- indiquez quelles preuves n’étaient pas disponibles ;
- ne modifiez pas WordPress, le code source, les données commerciales, les analyses, les systèmes externes ou le contenu publié.

Pourquoi ce prompt est structuré ainsi

Le prompt crée un contrat de preuve avant de demander des recommandations. Il rend les données manquantes visibles, réduit le risque qu’un modèle complète un enregistrement incomplet avec une prose plausible et produit une sortie qui peut être examinée systématiquement. Les champs structurés facilitent aussi la comparaison d’exécutions répétées ou la remise d’un sous-ensemble approuvé à un flux de travail d’implémentation ultérieur.

Une implémentation de production peut ajouter un schéma JSON, des entrées d’outils typées ou une validation automatisée. Ces mécanismes améliorent la cohérence, mais n’établissent pas que les preuves sources sont vraies, complètes ou actuelles. Un examen humain et une vérification propre au système demeurent requis.

Frontière d’accès recommandée

Utilisez Lecture seule pour l’étape décrite dans ce guide. Les capacités exactes offertes à une identité doivent provenir de la version de produit installée, du contrat de couverture publié et de la méthode de connexion réellement utilisée.

Ce qui doit rester en dehors de cette tâche

• Requêtes de production
• Exposition de secrets
• Exemples fabriqués
• Généralisation des permissions
• Changements cassants non documentés

Une action refusée peut être une preuve utile que la frontière de contrôle fonctionne. Ne répondez pas à un refus prévu en accordant un compte administrateur étendu ou Full Power. Déterminez d’abord si l’action appartient réellement au mandat actuel. Si c’est le cas, créez une étape autorisée séparément avec la capacité requise la plus étroite.

Comment WP Agent Control s’intègre

Le dossier privé guidé pour Claude Code ou Codex utilise l’API REST WordPress et un mot de passe d’application avec un profil dédié en lecture seule. Les profils Read Only, Draft, Content Editor et Publisher existants restent dans les options avancées. Ils ne sont pas automatiquement convertis à OAuth et ne reprennent pas le modèle de tâches distantes et d’approbation exacte.

Obtenez des informations structurées sur le site et examinez des pages publiées après la connexion. Cette lecture publique ne nécessite aucune tâche temporaire. Vous pouvez aussi consulter les pages publiques sans le plugin ; Agent Control ajoute un accès structuré et la continuité vers du travail WordPress autorisé.

Connecter votre IA : docs first profile · Voir les fonctions et la compatibilité : coverage

Liste de contrôle de vérification

• ☐ La tâche, la population, la période, l’environnement et la décision sont explicites.
• ☐ Chaque observation importante est liée à des preuves exactes ou étiquetée comme hypothèse.
• ☐ Les ID stables, URL, versions, dates, unités, paramètres régionaux et dénominateurs sont préservés.
• ☐ Les preuves manquantes et les limites de couverture restent visibles.
• ☐ L’identité analytique ou de recherche n’a effectué aucune mutation interdite.
• ☐ Un propriétaire qualifié a examiné les implications de sécurité, d’accessibilité, juridiques, commerciales ou de publication, s’il y a lieu.
• ☐ Toute implémentation a un mandat, un niveau d’accès, une sauvegarde et un plan de vérification distincts.
• ☐ Les identités temporaires, fixtures et preuves sensibles sont révoquées, réinitialisées ou éliminées après la tâche.

Modes de défaillance courants

• Documentation fondée uniquement sur le code source : l’enregistrement conditionnel ou les filtres à l’exécution font différer l’ensemble de routes déployé de celui que l’assistant a lu dans le code.
• Exemples limités aux succès : les consommateurs n’apprennent rien sur les réponses de validation, d’autorisation ou de conflit.
• Administrateur égale autorisé : la référence décrit de vastes suppositions de rôle plutôt que le callback de permission réel.
• Référence générée obsolète : la documentation n’est pas liée à la CI et dérive du package publié.

Une défaillance transversale récurrente est la dérive des permissions : la tâche initiale rencontre une limite et l’opérateur élargit l’accès avant de déterminer si l’opération manquante est nécessaire, prise en charge ou sûre. Cela détruit la valeur probante du refus et rend les résultats ultérieurs difficiles à attribuer.

Note avancée

Générez la documentation à partir d’une représentation intermédiaire versionnée qui combine les routes enregistrées, les schémas et les tests de contrat exécutés. Les explications rédigées par des humains peuvent ensuite enrichir la référence sans devenir une deuxième autorité pour les faits relatifs aux points de terminaison.

Guides connexes

• Comment créer une matrice de test des autorisations WordPress pour les agents IA
• Comment examiner le code d’une extension WordPress avec l’IA
• Guide de l’API Abilities de WordPress pour les flux de travail avec l’IA
• Comment exposer une Ability WordPress personnalisée par MCP

Étape suivante

Poursuivez avec le guide de soutien le plus pertinent et utilisez le guide des niveaux d’accès avant toute tâche authentifiée. Lorsque l’accès WordPress temporaire n’est plus nécessaire, terminez en révoquant l’identité.