Script

Script es un endpoint de backend declarativo que un frontend llama por HTTP. En lugar de escribir código de servidor, se declara «qué hacer» como JSON y el motor de WEEGLOO se encarga de ejecutarlo. El objetivo es reemplazar con un solo Script la típica fontanería de backend que sostiene un frontend (un BFF, Backend-for-Frontend): la autenticación, las comprobaciones de condiciones (guards), el CRUD encadenado, las llamadas a API externas y la transformación de valores.

Este conjunto de documentos es la referencia de la sintaxis de Script. Los detalles de cada parte de la sintaxis se reparten entre las páginas de Documentos de este grupo, más abajo.

Script se crea y se ejecuta en CMA (con la identidad de Weegloo User). Con la identidad de un miembro registrado en el producto (un ServiceUser), se puede usar de la misma forma también en ACMA. La API de Script existe solo en estas dos API de gestión (CMA, ACMA); no existe en las API de entrega de solo lectura (CDA, ACDA).

Modelo mental

• Un Script es un endpoint HTTP. El método de llamada (method) determina qué Script se ejecuta.
• El cuerpo es un array statements. Se ejecutan de forma secuencial, de arriba abajo. Es igual que el cuerpo de una función en la programación habitual.
• Es declaración, no código. No se inserta código arbitrario (FaaS), sino que se combinan tipos de statement predefinidos. Está diseñado menos para escribirse a mano por una persona y más para que lo genere un agente de IA a través de MCP.
• Los valores fluyen a través de plantillas de JSON Pointer. Se referencia el resultado del paso anterior, el payload de entrada o una variable con { /pointer } y se pasa al paso siguiente. Cuando hace falta una condición o un cálculo, se usan los operadores de JsonLogic. Las reglas completas se tratan en Expresiones de valor.

Estructura de nivel superior (ScriptDefinition)

Un Script se define con la siguiente estructura ScriptDefinition.

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. El método HTTP con el que se empareja al llamar (obligatorio)
  "payloadSchema": { /* ... */ }, // (opcional) JSON Schema. Si está presente, valida el payload de la petición antes de la ejecución
  "executionMode": "Sync",        // "Sync" | "Async" (obligatorio)
  "statements": [ /* Statement[]. Se ejecutan de arriba abajo (obligatorio, 1 o más) */ ]
}

El payload solo acepta JSON. Al cuerpo de la llamada se accede a través de la raíz de contexto /payload ({ /payload/... }). Las cabeceras HTTP de la petición de la llamada se referencian a través de la raíz /headers ({ /headers/... }, con las claves en minúsculas). El conjunto completo de raíces de contexto se trata en Expresiones de valor.

Petición y respuesta

Al final, un Script devuelve a quien hace la llamada el valor de su statement Return. La forma de la respuesta (o del resultado del sondeo Async) es la siguiente.

{
  "requestId": "…",     // Identificador de ejecución (en Async se sondea el resultado con este id)
  "durationMs": 1234,   // Tiempo de ejecución (ms)
  "statusCode": 200,    // El statusCode del Return alcanzado (por defecto 200)
  "return": <value>     // Solo cuando Return.isError es false. Si el valor es null, ""
  // "error": <value>   // Solo cuando Return.isError es true (en cuyo caso no está "return"). Si el valor es null, ""
}

• return y error nunca aparecen juntos. El isError del statement Return decide cuál de los dos es.
• Si el Script termina sin alcanzar un statement Return, return y error están ambos ausentes y statusCode es el valor por defecto (200).
• Si un valor es null, ese campo se emite como una cadena vacía "".

Con value, isError y statusCode de Return se controlan el cuerpo de la respuesta y el código de estado. Los detalles se tratan en Return en el Catálogo de statements.

Modos de ejecución: Sync y Async

• Si hay I/O externa, solo se permite Async. Si cualquier statement realiza una operación que pasa por la red, como una llamada externa Http (ExternalIo) o una ingesta de archivo de Media (MediaIngest, mediante url o base64), entonces executionMode debe ser obligatoriamente Async; si se intenta guardar como Sync, se rechaza en el momento de guardar. Esto es para no bloquear el hilo de la petición con la latencia externa.
• Es solo una diferencia en dónde se ejecuta; en cualquier caso, el resultado es el valor de Return.

Las reglas que conectan cada capacidad con el modo y los límites correspondientes se tratan en Semántica de ejecución, restricciones y seguridad.

Ejemplo mínimo

Crea un Content de publicación con el título y el cuerpo del payload de la petición, lo publica de inmediato y luego devuelve el sys.id creado.

{
  "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 crea el Content y vincula el resultado al nombre post.
• Return devuelve { "id": <nuevo Content id> } con 201.
• El motivo por el que los valores de fields de un Content son mapas de locale ({ "en-US": ... }) se trata en Mapas de locale en Expresiones de valor.

Hay más escenarios variados en el Cookbook.

Documentos de este grupo

• Expresiones de valor: trata las referencias { /pointer }, los literales, las operaciones y condiciones de JsonLogic, las raíces de contexto y los mapas de locale. Es el núcleo de la sintaxis.
• Catálogo de statements: trata los campos y los resultados de los 17 tipos de statement (CRUD y lecturas de recursos, Http, SetVar, If, Loop, Parallel, Try, Return).
• Semántica de ejecución, restricciones y seguridad: trata el orden de ejecución, los guards, la compensación, el bloqueo optimista, los errores, las restricciones estáticas y los límites de plan, y el modelo de seguridad.
• Cookbook: trata ejemplos completos como upsert, un guard de créditos, un proxy de LLM, la paginación, la ejecución en paralelo y una saga de pago.
• Recurso Script y endpoints: trata la estructura sys del recurso Script, y la especificación de los endpoints HTTP de creación y ejecución (/execute).

Si es la primera vez, recomendamos leer a partir de esta página en el orden Expresiones de valor y luego Catálogo de statements. El Cookbook también se puede hojear entero.