Giao diện

API reference ​

Data Sources ​

dataSources:list ​

Danh sách tất cả data source kèm status.

GET /api/dataSources:list

Response:

json
{
  "data": [
    {
      "key": "main",
      "displayName": "Main Database",
      "type": "main",
      "enabled": true,
      "fixed": true,
      "status": "loaded"
    },
    {
      "key": "ext-pg",
      "displayName": "External Postgres",
      "type": "postgres",
      "enabled": true,
      "fixed": false,
      "status": "loaded"
    }
  ]
}

dataSources:listEnabled ​

Data source đang bật (không bao gồm main).

GET /api/dataSources:listEnabled

dataSources:create ​

Tạo kết nối data source mới. Plugin tự động test connection trước khi lưu.

POST /api/dataSources:create
Body: {
  "key": "ext-pg",
  "displayName": "External Postgres",
  "type": "postgres",
  "enabled": true,
  "options": {
    "host": "db.example.com",
    "port": 5432,
    "database": "external_db",
    "username": "reader",
    "password": "***"
  }
}

Sau khi tạo:

  1. Test connection → fail sẽ trả lỗi, không lưu.
  2. INSERT dataSources row.
  3. Factory tạo DataSource instance.
  4. Introspect tables → tạo dataSourcesCollections + dataSourcesFields.
  5. Load ACL cho data source mới.

dataSources:update ​

Cập nhật cấu hình data source.

PUT /api/dataSources:update?filterByTk=ext-pg
Body: {
  "displayName": "External Postgres (updated)",
  "options": {
    "host": "new-db.example.com"
  }
}

Sau update, data source tự động reload (status: reloading → loaded).

dataSources:destroy ​

Xóa data source. Không thể xóa data source fixed: true (main).

DELETE /api/dataSources:destroy?filterByTk=ext-pg

Cascade xóa: dataSourcesCollections, dataSourcesFields, dataSourcesRoles*.

dataSources:testConnection ​

Test kết nối trước khi lưu.

POST /api/dataSources:testConnection
Body: {
  "type": "postgres",
  "options": {
    "host": "db.example.com",
    "port": 5432,
    "database": "external_db",
    "username": "reader",
    "password": "***"
  }
}

Response: 200 OK nếu kết nối thành công, 400 kèm error message nếu thất bại.

dataSources:refresh ​

Reload data source — introspect lại tables và sync collections.

POST /api/dataSources:refresh?filterByTk=ext-pg

dataSources:readTables ​

Đọc danh sách bảng từ database ngoài (chưa load vào collection).

GET /api/dataSources/ext-pg/readTables

dataSources:loadTables ​

Load bảng cụ thể vào collection.

POST /api/dataSources/ext-pg/loadTables
Body: {
  "tables": ["customers", "invoices"]
}

Remote Collections & Fields ​

dataSources.collections:list ​

Danh sách collection của data source.

GET /api/dataSources/ext-pg/collections:list

dataSources.collections:update ​

Override metadata collection (tên hiển thị, options).

PUT /api/dataSources/ext-pg/collections:update?filterByTk=customers
Body: {
  "title": "Khách hàng",
  "options": { "sortable": true }
}

dataSourcesCollections.fields:list ​

Danh sách field của collection trong data source.

GET /api/dataSources/ext-pg/collections/customers/fields:list

dataSourcesCollections.fields:create ​

Thêm field overlay — field bổ sung không tồn tại trong database ngoài.

POST /api/dataSources/ext-pg/collections/customers/fields:create
Body: {
  "name": "fullName",
  "type": "formula",
  "interface": "input",
  "options": { "expression": "firstName || ' ' || lastName" }
}

dataSourcesCollections.fields:update ​

Sửa field overlay.

PUT /api/dataSources/ext-pg/collections/customers/fields:update?filterByTk=fullName
Body: { "interface": "textarea" }

dataSourcesCollections.fields:destroy ​

Xóa field overlay (không ảnh hưởng database ngoài).

DELETE /api/dataSources/ext-pg/collections/customers/fields:destroy?filterByTk=fullName

Per-DataSource ACL ​

dataSources.roles:get ​

Lấy cấu hình role cho data source cụ thể.

GET /api/dataSources/ext-pg/roles:get?filterByTk=member

Response:

json
{
  "data": {
    "roleName": "member",
    "dataSourceKey": "ext-pg",
    "strategy": { "actions": ["view"] }
  }
}

dataSources.roles:update ​

Cập nhật strategy role cho data source.

PUT /api/dataSources/ext-pg/roles:update?filterByTk=member
Body: {
  "strategy": { "actions": ["view", "create", "update"] }
}

roles.dataSourceResources:create ​

Gán permission resource cho role trên data source.

POST /api/roles/member/dataSourceResources:create
Body: {
  "dataSourceKey": "ext-pg",
  "name": "customers",
  "usingActionsConfig": true,
  "actions": [
    { "name": "view", "fields": ["id", "name", "email"] },
    { "name": "create" }
  ]
}

roles.dataSourceResources:update ​

Cập nhật permission resource.

PUT /api/roles/member/dataSourceResources:update?filterByTk=<resourceId>
Body: {
  "actions": [
    { "name": "view" },
    { "name": "create" },
    { "name": "update", "fields": ["name", "email"] }
  ]
}

roles.dataSourcesCollections:list ​

Danh sách collection kèm trạng thái permission cho role.

GET /api/roles/member/dataSourcesCollections:list?dataSourceKey=ext-pg

Ví dụ sử dụng ​

Tạo kết nối PostgreSQL ​

typescript
await agent.resource('dataSources').testConnection({
  values: {
    type: 'postgres',
    options: { host: 'db.example.com', port: 5432, database: 'ext', username: 'app', password: 'secret' },
  },
});

const response = await agent.resource('dataSources').create({
  values: {
    key: 'ext-pg',
    displayName: 'External PG',
    type: 'postgres',
    enabled: true,
    options: { host: 'db.example.com', port: 5432, database: 'ext', username: 'app', password: 'secret' },
  },
});

Cấu hình ACL cho data source ​

typescript
await agent.resource('dataSources.roles', 'ext-pg').update({
  filterByTk: 'member',
  values: {
    strategy: { actions: ['view'] },
  },
});

await agent.resource('roles.dataSourceResources', 'member').create({
  values: {
    dataSourceKey: 'ext-pg',
    name: 'customers',
    usingActionsConfig: true,
    actions: [{ name: 'view' }, { name: 'update', fields: ['name'] }],
  },
});