Découverte de l'API

WebBlocks CMS expose une Content API axée sur la découverte, destinée aux outils d'IA et d'opérateur de confiance. Un outil externe ne devrait avoir besoin que de l'URL de base de l'API du CMS et d'un token d'API du CMS pour connaître les endpoints disponibles, les schémas, les exemples et le workflow de contenu sécurisé.

Pour les outils locaux d'IA ou d'opérateur, enregistrez l'URL de base de l'API plutôt que la racine publique du site :

La première requête devrait être :

GET /webadmin/api est délibérément sûr pour un usage public. Sans token Bearer valide, il ne renvoie qu'un JSON d'amorçage minimal :

• le nom du produit
• la version de l'API
• authenticated: false
• un lien vers elle-même
• un court message invitant l'appelant à s'authentifier

Il ne doit renvoyer ni l'inventaire des endpoints, ni les données du site, ni les contrats de contenu, ni les aperçus de tokens, ni les hachages de tokens, ni les détails des utilisateurs, ni les chemins locaux, ni les éléments internes du serveur.

Avec un token Bearer d'API du CMS valide, la découverte renvoie :

• product: WebBlocks CMS
• cms_version et product_version
• api_version
• authenticated: true
• les noms des capacités du token, sans la valeur du token, son aperçu ni son hachage
• les étapes suivantes recommandées
• les liens vers OpenAPI, le guide IA, le contrat de contenu, les exemples, validate/apply, les pages, la publication de page, la publication des blocs appartenant à la page, la navigation et les Shared Slots

La réponse authentifiée constitue le contrat d'amorçage canonique pour les outils d'IA et d'opérateur. Les outils devraient suivre les liens renvoyés plutôt que de supposer un accès au système de fichiers local du dépôt du CMS ou à la documentation du paquet.

Pour les plans de contenu, page.path et expected_path sont des chemins publics canoniques de Page Translation, tels que /contact ou /docs/internal-content-api. /p/... ne relève que de la compatibilité publique héritée et ne devrait pas être généré par les nouveaux outils.

Les liens de découverte actuels comprennent :

Les liens de validate/apply du contenu prennent en charge les modes de plan create_draft_page et replace_existing_draft_page. Utilisez GET /webadmin/api/content-contract pour obtenir la liste actuelle des modes et les règles de sécurité.

Les liens de publication exigent content.publish. POST /webadmin/api/pages/{page}/publish publie par défaut la page seule, avec include_page_owned_blocks: false ; il ne publie pas les blocs en brouillon à moins que la requête ne définisse explicitement include_page_owned_blocks: true. La publication en cascade des Shared Slots n'est pas prise en charge et renvoie un retour de validation au format JSON. POST /webadmin/api/pages/{page}/publish-page-owned-blocks publie les blocs éligibles appartenant à la page, en brouillon ou en revue, sans modifier le statut du workflow de la page.

GET /webadmin/api/examples/contact-page illustre un bloc natif contact_form. Il évite délibérément le Trusted HTML, le balisage de formulaire brut et les solutions de repli mailto:, afin que les outils puissent créer des pages de contact en brouillon sûres via le même contrat de blocs structuré que celui utilisé par les opérateurs dans l'administration.

Les liens protégés exigent :

Les tokens d'API du CMS exposent dans la découverte les capacités sélectionnées lors de la création du token, afin que les outils puissent connaître les actions autorisées avant de tenter des écritures.

Capacités standard de construction de pages :

• content.read
• content.validate
• content.apply
• navigation.write
• shared-slots.write

Les capacités destructrices ou de publication constituent des options avancées distinctes et ne sont pas sélectionnées par défaut :

• content.publish
• pages.delete

Les opérations destructrices doivent exiger une capacité correspondante explicite et ne devraient pas être accordées aux tokens ordinaires de construction de pages.

Les outils ordinaires de construction de pages ne devraient pas présumer que la publication est disponible. Si content.publish est absent, les outils devraient s'arrêter avant d'appeler les endpoints de publication et signaler qu'un token d'opérateur de confiance doté de la capacité de publication est requis.

Les endpoints de la Content API renvoient des erreurs JSON plutôt que des redirections du navigateur, des pages de connexion ou des réponses HTML CSRF. Les charges utiles d'erreur incluent des liens d'orientation le cas échéant :

• api_discovery_url
• openapi_url
• documentation_url
• example_url

Comportement attendu des statuts :

• 401 pour les tokens manquants, invalides ou révoqués
• 403 pour les capacités manquantes
• 422 pour les charges utiles de contenu invalides

Les réponses de découverte, OpenAPI, guide IA, exemples et contrat de contenu ne doivent exposer ni valeurs réelles de tokens, ni hachages de tokens, ni valeurs de .env, ni chemins du système de fichiers local, ni chemins serveur, ni traces d'exécution, ni exceptions brutes, ni éléments internes de la base de données, ni listes d'utilisateurs, ni détails privés d'opérateur.

Les URL d'aperçu telles que /webadmin/pages/{page}/preview sont des routes de navigateur ou d'administration. Elles nécessitent une session de navigateur d'administration authentifiée et ne s'ouvrent pas avec des tokens Bearer d'API du CMS. Une redirection vers la connexion depuis cette URL signifie que la session de navigateur est absente ; il ne s'agit pas d'un échec d'authentification de l'Internal Content API.