Script

Script est un endpoint backend déclaratif qu'un frontend appelle via HTTP. Au lieu d'écrire du code serveur, on déclare « quoi faire » sous forme de JSON, et le moteur WEEGLOO se charge de l'exécuter. L'objectif est de remplacer, avec un seul Script, la tuyauterie backend typique qui soutient un frontend (un BFF, Backend-for-Frontend) : l'authentification, les vérifications de condition (guards), le CRUD enchaîné, les appels à des API externes et la transformation de valeurs.

Cet ensemble de documents constitue la référence de la syntaxe de Script. Les détails de chaque partie de la syntaxe sont répartis entre les pages listées dans Documents de ce groupe, plus bas.

Script se crée et s'exécute sur CMA (avec l'identité Weegloo User). Sous l'identité d'un membre inscrit au produit (un ServiceUser), on peut l'utiliser de la même manière sur ACMA également. L'API Script n'existe que sur ces deux API de gestion (CMA, ACMA) ; elle n'existe pas sur les API de livraison en lecture seule (CDA, ACDA).

Modèle mental

• Un Script est un endpoint HTTP. La méthode d'appel (method) détermine quel Script s'exécute.
• Le corps est un tableau statements. Ils s'exécutent séquentiellement, de haut en bas. C'est exactement comme le corps d'une fonction en programmation classique.
• C'est une déclaration, pas du code. On n'insère pas de code arbitraire (FaaS) ; on combine des types de statement prédéfinis. Il est conçu moins pour être rédigé à la main par une personne que pour être généré par un agent d'IA via MCP.
• Les valeurs circulent à travers des modèles JSON Pointer. On référence le résultat de l'étape précédente, le payload d'entrée ou une variable avec { /pointer }, puis on le transmet à l'étape suivante. Lorsqu'une condition ou un calcul est nécessaire, on utilise les opérateurs JsonLogic. Les règles complètes sont traitées dans Expressions de valeur.

Structure de niveau supérieur (ScriptDefinition)

Un Script se définit avec la structure ScriptDefinition suivante.

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. La méthode HTTP mise en correspondance lors de l'appel (obligatoire)
  "payloadSchema": { /* ... */ }, // (facultatif) JSON Schema. Si présent, valide le payload de la requête avant l'exécution
  "executionMode": "Sync",        // "Sync" | "Async" (obligatoire)
  "statements": [ /* Statement[]. Exécutés de haut en bas (obligatoire, au moins 1) */ ]
}

Le payload n'accepte que du JSON. Le corps de l'appel est accessible via la racine de contexte /payload ({ /payload/... }). Les en-têtes HTTP de la requête de l'appel se référencent via la racine /headers ({ /headers/... }, avec des clés en minuscules). L'ensemble complet des racines de contexte est traité dans Expressions de valeur.

Requête et réponse

Au final, un Script renvoie à l'appelant la valeur de son statement Return. La forme de la réponse (ou du résultat du sondage Async) est la suivante.

{
  "requestId": "…",     // Identifiant d'exécution (pour Async, sonder le résultat avec cet id)
  "durationMs": 1234,   // Durée d'exécution (ms)
  "statusCode": 200,    // Le statusCode du Return atteint (200 par défaut)
  "return": <value>     // Uniquement lorsque Return.isError vaut false. Si la valeur est null, ""
  // "error": <value>   // Uniquement lorsque Return.isError vaut true (dans ce cas "return" est absent). Si la valeur est null, ""
}

• return et error n'apparaissent jamais ensemble. Le isError du statement Return détermine lequel des deux apparaît.
• Si le Script se termine sans atteindre de statement Return, return et error sont tous deux absents et statusCode prend la valeur par défaut (200).
• Si une valeur est null, ce champ est émis sous forme de chaîne vide "".

Le corps de la réponse et le code de statut se contrôlent avec les value, isError et statusCode du statement Return. Pour les détails, voir Return dans le Catalogue des statements.

Modes d'exécution : Sync et Async

• S'il y a des I/O externes, seul Async est autorisé. Si un statement quelconque effectue une opération réseau, comme un appel externe Http (ExternalIo) ou une ingestion de fichier Media (MediaIngest, via url ou base64), alors executionMode doit obligatoirement valoir Async ; si l'on tente de l'enregistrer en Sync, il est rejeté au moment de l'enregistrement. Cela évite que le thread de la requête soit bloqué par la latence externe.
• Ce n'est qu'une différence d'emplacement d'exécution ; dans les deux cas, le résultat est la valeur de Return.

Les règles selon lesquelles une capacité donnée impose un mode, ainsi que les limites applicables, sont traitées dans Sémantique d'exécution, contraintes et sécurité.

Exemple minimal

Cet exemple crée un Content d'article à partir du titre et du corps du payload de la requête, le publie aussitôt, puis renvoie le sys.id créé.

{
  "method": "Post",
  "executionMode": "Sync",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

• ResourceCreate crée le Content et lie le résultat au nom post.
• Return renvoie { "id": <nouveau Content id> } avec 201.
• La raison pour laquelle les valeurs de fields d'un Content sont des mappages de locale ({ "en-US": ... }) est traitée dans Mappages de locale dans les Expressions de valeur.

On trouvera des scénarios plus variés dans le Cookbook.

Documents de ce groupe

• Expressions de valeur : traite les références { /pointer }, les littéraux, les opérations et conditions JsonLogic, les racines de contexte et les mappages de locale. C'est le cœur de la syntaxe.
• Catalogue des statements : traite les champs et les résultats des 17 types de statement (CRUD et lectures de ressources, Http, SetVar, If, Loop, Parallel, Try, Return).
• Sémantique d'exécution, contraintes et sécurité : traite l'ordre d'exécution, les guards, la compensation, le verrouillage optimiste, les erreurs, les contraintes statiques et les limites de plan, ainsi que le modèle de sécurité.
• Cookbook : traite des exemples complets tels que l'upsert, un guard de crédits, un proxy LLM, la pagination, l'exécution en parallèle et une saga de paiement.
• Ressource Script et endpoints : traite la structure sys de la ressource Script, ainsi que la spécification des endpoints HTTP de création et d'exécution (/execute).

Si c'est votre première fois, nous recommandons de lire, à partir de cette page, dans l'ordre Expressions de valeur puis Catalogue des statements. Le Cookbook mérite aussi d'être parcouru en entier.