Skip to content
Verified

API

A callable endpoint of the project, internal through call_project_api or external through the api/mcp endpoint.

An API program is an orchestration layer with one output: it can bind a datasource, coordinate get_data, set_data and batch calls inside its own events, and hand back one response, shaped by a template rather than by field bindings. Call it from inside the project with the call_project_api workflow action, or reach it from outside through the project's api/mcp endpoint.

Properties

progDataSource and progFields

Same shape as Datasource, used when the API reads or writes a table as part of building its response. progFields declares the fields available to the response template, table for real columns, virtual for computed ones.

scriptData: the response template

The payload is a stringified object template on scriptData.value; @field bindings resolve at call time, the same expression syntax as everywhere else in the platform:

json
{ "value": "{\n   CS_Id: @CS_Id,\n   CS_Class_Id: @CS_Class_Id,\n   CS_School_Id: @CS_School_Id\n}" }

Calling an API program

Internally, call_project_api runs it exactly like get_data or set_data runs their program types, name.prog names the API's id, name.parameters supplies its inputs.

Worked example

Declare the interface

progParams for each input (dir: "in") and output (dir: "out") value.

Bind data if the response needs it

An optional progDataSource, plus progFields for whichever columns feed the template.

Write the response template

scriptData.value, a stringified object with @field placeholders, and set apiOutput to the format callers should get back.

Create an API node under Programs, set apiOutput on its Properties tab, optionally bind a Datasource, then write the response shape in the Response editor.

xml
<meta lang="json5">
{
  id: "student_classes_api",
  menuTitle: "Student Dashboard API",
  apiOutput: "json"
}
</meta>

<params lang="json5">
{
  in: { campus_in: "string", active_view_in: "string" }
}
</params>

<response>
({
  ok: true,
  campus: @campus_in,
  activeView: @active_view_in,
  summary: { students: 3, tasks: 3, profiles: 3 }
})
</response>

The .xu <response> block is scriptData.value, written as a plain object expression rather than a JSON string.

json
{
  "properties": {
    "menuType": "api", "menuName": "Student Classes", "apiOutput": "json",
    "progParams": [{ "id": 1734434656288, "data": { "dir": "in", "parameter": "user_id_in", "type": "string" }, "props": {} }]
  },
  "progDataSource": {
    "dataSourceType": "table", "dataSourceFilterModelType": "index",
    "dataSourceTableId": "5b1_tbl_…", "dataSourceIndexId": "be2d06c8-…"
  },
  "progFields": [
    { "id": 1489199308774, "data": { "type": "table", "field_id": "CS_Id" }, "props": { "fieldType": "string" } }
  ],
  "scriptData": { "value": "{\n   CS_Id: @CS_Id\n}" }
}