Giao diện

API reference ​

Collections ​

collections:list ​

Danh sách tất cả collection (metadata).

GET /api/collections:list?paginate=false

collections:listMeta ​

Danh sách collection đã load kèm field metadata.

GET /api/collections:listMeta?paginate=false

Response bao gồm fields, category, options cho mỗi collection.

collections:create ​

Tạo collection mới. Plugin tự động migrate (CREATE TABLE).

POST /api/collections:create
Body: {
  "name": "orders",
  "title": "Đơn hàng",
  "fields": [
    { "name": "title", "type": "string", "interface": "input" },
    { "name": "amount", "type": "float", "interface": "number" },
    { "name": "status", "type": "string", "interface": "select" }
  ]
}

Sau khi tạo:

  1. INSERT metadata vào collections + fields.
  2. CollectionModel.load() → tạo Collection instance.
  3. CollectionModel.migrate() → CREATE TABLE t_orders.
  4. sendSyncMessage → đồng bộ sang cluster instances.

collections:update ​

Cập nhật collection metadata.

PUT /api/collections:update?filterByTk=orders
Body: {
  "title": "Đơn hàng (cập nhật)",
  "description": "Quản lý đơn hàng"
}

collections:destroy ​

Xóa collection — cascade remove fields, FK constraints, drop table.

DELETE /api/collections:destroy?filterByTk=orders

WARNING

Xóa collection sẽ DROP TABLE vật lý. Dữ liệu trong bảng sẽ mất vĩnh viễn.

collections:setFields ​

Bulk replace toàn bộ fields cho collection (transactional).

POST /api/collections:setFields?filterByTk=orders
Body: {
  "fields": [
    { "name": "title", "type": "string" },
    { "name": "amount", "type": "float" },
    { "name": "newField", "type": "text" }
  ]
}

Fields không có trong danh sách mới sẽ bị xóa (cascade drop column).

Fields ​

fields:list ​

Danh sách fields của collection.

GET /api/collections/orders/fields:list

fields:create ​

Thêm field mới.

POST /api/collections/orders/fields:create
Body: {
  "name": "customerName",
  "type": "string",
  "interface": "input",
  "description": "Tên khách hàng"
}

Sau khi tạo: ALTER TABLE t_orders ADD COLUMN customer_name VARCHAR(255).

fields:update ​

Cập nhật field metadata (title, interface, description...).

PUT /api/collections/orders/fields:update?filterByTk=customerName
Body: {
  "description": "Tên khách hàng (bắt buộc)"
}

fields:destroy ​

Xóa field — cascade drop column, remove FK nếu có.

DELETE /api/collections/orders/fields:destroy?filterByTk=customerName

Composite Constraints ​

collections:createCompositeConstraint ​

Tạo unique constraint trên nhiều field.

POST /api/collections/orders/compositeConstraints:create
Body: {
  "fields": ["customerId", "orderDate"],
  "type": "unique"
}

collections:updateCompositeConstraint ​

Cập nhật constraint.

PUT /api/collections/orders/compositeConstraints:update?filterByTk=<constraintId>
Body: { "fields": ["customerId", "orderDate", "type"] }

collections:deleteCompositeConstraint ​

Xóa constraint.

DELETE /api/collections/orders/compositeConstraints:destroy?filterByTk=<constraintId>

Database Views ​

dbViews:list ​

Danh sách DB view chưa kết nối collection.

GET /api/dbViews:list

dbViews:get ​

Infer fields từ view — trả về danh sách field tự động nhận diện.

GET /api/dbViews:get?filterByTk=v_order_summary

dbViews:query ​

Query trực tiếp từ view (có phân trang).

GET /api/dbViews:query?filterByTk=v_order_summary&page=1&pageSize=20

Main Data Source ​

mainDataSource:refresh ​

Reload tất cả collection từ metadata. Dùng khi metadata bị sửa trực tiếp hoặc sau migrate.

POST /api/mainDataSource:refresh

mainDataSource:syncFields ​

Đồng bộ fields từ database vật lý vào metadata (reverse engineering). Phát hiện column mới, column đã xóa.

POST /api/mainDataSource:syncFields?filterByTk=orders

Ví dụ sử dụng ​

Tạo collection với relation ​

typescript
await agent.resource('collections').create({
  values: {
    name: 'orders',
    title: 'Đơn hàng',
    fields: [
      { name: 'title', type: 'string', interface: 'input' },
      { name: 'amount', type: 'float', interface: 'number' },
      {
        name: 'customer',
        type: 'belongsTo',
        interface: 'obo',
        target: 'users',
        foreignKey: 'customerId',
      },
    ],
  },
});

Sync fields từ database ​

typescript
await agent.resource('mainDataSource').syncFields({
  filterByTk: 'orders',
});

const fields = await agent.resource('collections.fields', 'orders').list();