API设置（REST API）

斑斑低代码提供REST API，可用于读取、搜索、新增、修改和删除表单数据，也可以上传文件。

调用API前，需要先在应用中开启API服务。部分读取接口可以设置为公开访问，其他请求需要通过Key-Secret完成鉴权。

1. API 设置

打开应用，点击右上角“应用设置”，然后进入“API 设置”。

API设置页面包含以下配置：

应用API地址格式如下：

https://你的工作台地址/api/v1/:appId

其中，:appId 可以使用应用ID，也可以使用应用别名。

修改API设置后，需要点击“保存”使配置生效。

2. Key-Secret 校验

除公开读取接口外，开放API使用Key-Secret进行请求鉴权。

以下请求必须进行Key-Secret校验：

2.1 获取 key-secret

Key和Secret由工作台管理员在工作台管理后台中查看。

仅工作台管理员可以查看或重置Key-Secret。重置后，原有Key和Secret会立即失效。

鉴权参数仅通过 URL 查询参数传递，不需要额外携带“Authorization”、“X-API-Key”等鉴权Header。请求体Header按接口要求设置：文件上传使用 “Content-Type: multipart/form-data”，JSON写入接口使用“Content-Type: application/json”。

需要鉴权的请求必须在URL查询参数中携带以下字段：

服务端会校验时间戳。客户端时间与服务端时间相差超过60秒时，请求会被拒绝。

签名计算方式：

md5(key + timestamp + secret)

例如：

key       = demoKey123
secret    = demoSecret456
timestamp = 1784253600
sign      = 743a42bbe310a73837141ee4f2da2b9e

完整鉴权参数：

--url-query "key=demoKey123" 
--url-query "timestamp=1784253600" 
--url-query "sign=743a42bbe310a73837141ee4f2da2b9e"

示例时间戳仅用于说明。实际请求必须使用当前时间戳，并重新计算sign。

Secret不应写入浏览器前端代码或公开仓库，建议在服务端生成签名。

3. API 列表

以下示例统一使用这些数据：

接口总览：

除id、createTime等系统字段外，其余字段名称取决于表单的字段别名。

开放API中常见的系统字段包括：

3.1 获取应用内的所有表单

3.1.1 请求

3.1.2 查询参数

无

3.1.3 请求体

无

3.1.4 请求示例

curl "https://workspace.example.com/api/v1/4j815fmhht0j"

3.1.5 响应体

3.1.6 响应体示例

{
  "data": [
    {
      "id": "frm_articles_01",
      "name": "articles"
    },
    {
      "id": "frm_categories_01",
      "name": "categories"
    }
  ]
}

3.1.7 失败结果

应用不存在或未开启API服务时返回HTTP 400：

{
  "error": {
    "code": 400,
    "message": "API未启用"
  }
}

3.2 获取数据列表

3.2.1 请求

3.2.2 查询参数

分页同时传入两种格式时，优先使用start/limit。

过滤支持以下操作符：

$eq、$ne、$gt、$gte、$lt、$lte、$in、$nin、
$all、$size、$like、$exists、$and、$or、$not

3.2.3 请求体

无

3.2.4 请求示例

curl --get "https://workspace.example.com/api/v1/4j815fmhht0j/articles" 
  --url-query "pagination[page]=1" 
  --url-query "pagination[pageSize]=2" 
  --url-query "sort=createTime:desc"

未开启公开读数据时：

curl --get "https://workspace.example.com/api/v1/4j815fmhht0j/articles" 
  --url-query "pagination[page]=1" 
  --url-query "pagination[pageSize]=2" 
  --url-query "key=demoKey123" 
  --url-query "timestamp=1784253600" 
  --url-query "sign=743a42bbe310a73837141ee4f2da2b9e"

3.2.5 响应体

除系统字段外，实际返回字段由表单字段别名以及fields、populate参数决定。

3.2.6 响应体示例

{
  "data": [
    {
      "id": "u2i3s0pi1no7",
      "title": "BMK Paris Bamako",
      "description": "位于巴黎的餐厅",
      "updateTime": "2026-07-17 10:05:00",
      "createTime": "2026-07-17 10:05:00"
    },
    {
      "id": "stykuonikdfl",
      "title": "Biscotte Restaurant",
      "description": "提供法式简餐",
      "updateTime": "2026-07-17 10:00:00",
      "createTime": "2026-07-17 10:00:00"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 2,
      "pageCount": 1,
      "total": 2
    }
  }
}

3.2.7 失败结果

未开启公开读数据且鉴权失败时返回HTTP 400：

{
  "error": {
    "code": 400,
    "message": "key-secret校验未通过"
  }
}

3.3 获取单条数据

3.3.1 请求

3.3.2 查询参数

3.3.3 请求体

无

3.3.4 请求示例

curl --get "https://workspace.example.com/api/v1/4j815fmhht0j/articles/stykuonikdfl" 
  --url-query "fields[0]=id" 
  --url-query "fields[1]=title" 
  --url-query "fields[2]=description"

3.3.5 响应体

3.3.6 响应体示例

{
  "data": {
    "id": "stykuonikdfl",
    "title": "Biscotte Restaurant",
    "description": "提供法式简餐"
  },
  "meta": {}
}

3.3.7 失败结果

应用或表单不存在时返回 HTTP 400：

{
  "error": {
    "code": 400,
    "message": "表单不存在"
  }
}

数据ID不存在时，当前接口可能返回HTTP 200，但没有data：

{
  "meta": {}
}

调用方应检查响应中是否存在data。

3.4 获取目录树数据

3.4.1 请求

该接口仅适用于已配置文档目录视图的表单。

3.4.2 查询参数

3.4.3 请求体

无。

3.4.4 请求示例

curl "https://workspace.example.com/api/v1/4j815fmhht0j/articles/toc"

3.4.5 响应体

3.4.6 响应体示例

{
  "data": [
    {
      "id": "cat_food",
      "title": "餐饮",
      "type": "catalog",
      "createTime": "2026-07-17 09:00:00",
      "updateTime": "2026-07-17 09:00:00",
      "children": [
        {
          "id": "stykuonikdfl",
          "title": "Biscotte Restaurant",
          "type": "document",
          "createTime": "2026-07-17 10:00:00",
          "updateTime": "2026-07-17 10:00:00"
        }
      ]
    }
  ],
  "meta": {}
}

3.4.7 失败结果

表单未配置文档目录视图时可能返回HTTP 400：

{
  "error": {
    "code": -1,
    "message": "无法读取目录视图配置"
  }
}

3.5 全文搜索表单数据

3.5.1 请求

3.5.2 查询参数

3.5.3 请求体

无

3.5.4 请求示例

curl --get "https://workspace.example.com/api/v1/4j815fmhht0j/articles/search" 
  --url-query "query=Biscotte" 
  --url-query "pagination[page]=1" 
  --url-query "pagination[pageSize]=10"

3.5.5 响应体

搜索接口当前不保证返回有效的total和pageCount。

3.5.6 响应体示例

{
  "data": [
    {
      "id": "stykuonikdfl",
      "title": "Biscotte Restaurant",
      "description": "提供法式简餐",
      "updateTime": "2026-07-17 10:00:00",
      "createTime": "2026-07-17 10:00:00"
    }
  ],
  "meta": {
    "tokens": [
      "Biscotte"
    ],
    "pagination": {
      "page": 1,
      "pageSize": 10
    }
  }
}

3.5.7 失败结果

表单不存在时返回 HTTP400：

{
  "error": {
    "code": 400,
    "message": "表单不存在"
  }
}

3.6 上传文件

3.6.1 请求

3.6.2 查询参数

3.6.3 请求体

文件字段名必须为file。

3.6.4 请求示例

curl --request POST 
  --url "https://workspace.example.com/api/v1/4j815fmhht0j/file" 
  --url-query "key=demoKey123" 
  --url-query "timestamp=1784253600" 
  --url-query "sign=743a42bbe310a73837141ee4f2da2b9e" 
  --form "file=@./menu.pdf"

3.6.5 响应体

3.6.6 响应体示例

{
  "name": "menu.pdf",
  "uid": 1784253600123,
  "status": "success",
  "size": 125604,
  "url": "uploads/4j815fmhht0j/0cc175b9c0f1b6a831c399e269772661.pdf",
  "md5": "0cc175b9c0f1b6a831c399e269772661"
}

3.6.7 失败结果

鉴权失败时返回HTTP 400：

{
  "error": {
    "code": 400,
    "message": "key-secret校验未通过"
  }
}

文件处理失败时，当前接口可能返回：

{
  "url": null
}

3.7 创建数据

3.7.1 请求

未传入id时创建数据。传入已存在的id时，当前接口会更新对应数据；传入不存在的 id时会按该ID创建数据。

3.7.2 查询参数

3.7.3 请求体

3.7.4 请求体示例

curl --request POST \
  --url "https://workspace.example.com/api/v1/4j815fmhht0j/articles" 
  --url-query "key=demoKey123" 
  --url-query "timestamp=1784253600" 
  --url-query "sign=743a42bbe310a73837141ee4f2da2b9e" 
  --header "Content-Type: application/json" 
  --data '{
    "data": {
      "title": "Biscotte Restaurant",
      "description": "提供法式简餐"
    }
  }'

3.7.5 响应体

写接口返回的data按当前实现可能使用内部字段ID，与读取接口中的字段别名不同。

3.7.6 响应体示例

{
  "tableName": "articles",
  "data": [
    {
      "f_title_01": "Biscotte Restaurant",
      "f_description_01": "提供法式简餐",
      "_uuid": "stykuonikdfl",
      "_create_time": "2026-07-17 10:00:00",
      "_update_time": "2026-07-17 10:00:00",
      "_data_stage": "normal"
    }
  ],
  "success": true
}

f_title_01、f_description_01仅为内部字段ID示例，实际值由表单决定。

3.7.7 失败结果

字段校验、权限或数据写入失败时返回HTTP 400：

{
  "error": {
    "code": -1,
    "message": "数据校验失败"
  }
}

3.8 按数据 ID 修改数据

3.8.1 请求

3.8.2 查询参数

3.8.3 请求体

3.8.4 请求示例

curl --request PUT 
  --url "https://workspace.example.com/api/v1/4j815fmhht0j/articles/stykuonikdfl" 
  --url-query "key=demoKey123" 
  --url-query "timestamp=1784253600" 
  --url-query "sign=743a42bbe310a73837141ee4f2da2b9e" 
  --header "Content-Type: application/json" 
  --data '{
    "data": {
      "title": "Biscotte Restaurant（更新）",
      "description": "更新后的餐厅介绍"
    }
  }'

3.8.5 响应体

3.8.6 响应体示例

{
  "tableName": "articles",
  "data": [
    {
      "f_title_01": "Biscotte Restaurant（更新）",
      "f_description_01": "更新后的餐厅介绍",
      "_uuid": "stykuonikdfl",
      "_create_time": "2026-07-17 10:00:00",
      "_update_time": "2026-07-17 10:30:00",
      "_data_stage": "normal"
    }
  ],
  "success": true
}

3.8.7 失败结果

数据不存在或修改失败时返回HTTP 400：

{
  "error": {
    "code": -1,
    "message": "更新数据失败"
  }
}

3.9 按筛选条件修改首条匹配数据

3.9.1 请求

当前接口不是批量修改接口。请使用能够唯一定位数据的过滤条件。

3.9.2 查询参数

3.9.3 请求体

3.9.4 请求示例

curl --request PUT \
  --url "https://workspace.example.com/api/v1/4j815fmhht0j/articles" 
  --url-query 'filters[id][$eq]=stykuonikdfl' 
  --url-query "key=demoKey123" 
  --url-query "timestamp=1784253600" 
  --url-query "sign=743a42bbe310a73837141ee4f2da2b9e" 
  --header "Content-Type: application/json" 
  --data '{
    "data": {
      "description": "按筛选条件更新的餐厅介绍"
    }
  }'

3.9.5 响应体

3.9.6 响应体示例

{
  "tableName": "articles",
  "data": [
    {
      "id": "stykuonikdfl",
      "title": "Biscotte Restaurant（更新）",
      "description": "按筛选条件更新的餐厅介绍",
      "updateTime": "2026-07-17 10:35:00",
      "createTime": "2026-07-17 10:00:00"
    }
  ],
  "success": true
}

3.9.7 失败结果

没有数据符合过滤条件时，当前接口返回HTTP 200：

{
  "tableName": "articles",
  "data": [],
  "success": true
}

鉴权失败时返回HTTP 400：

{
  "error": {
    "code": 400,
    "message": "key-secret校验未通过"
  }
}

3.10 删除数据

3.10.1 请求

3.10.2 查询参数

3.10.3 请求体

无

3.10.4 请求示例

curl --request DELETE 
  --url "https://workspace.example.com/api/v1/4j815fmhht0j/articles/stykuonikdfl" 
  --url-query "key=demoKey123" 
  --url-query "timestamp=1784253600" 
  --url-query "sign=743a42bbe310a73837141ee4f2da2b9e"

3.10.5 响应体

删除接口返回JSON，不是204空响应。

3.10.6 响应体示例

{
  "tableName": "articles",
  "success": true,
  "data": [
    {
      "_uuid": "stykuonikdfl",
      "f_title_01": "Biscotte Restaurant（更新）",
      "f_description_01": "按筛选条件更新的餐厅介绍",
      "_data_stage": "deleting"
    }
  ],
  "mutationApplied": true,
  "partialSuccess": false,
  "successCount": 1,
  "failedCount": 0,
  "permissionDeniedCount": 0,
  "successRows": [
    {
      "_uuid": "stykuonikdfl",
      "f_title_01": "Biscotte Restaurant（更新）",
      "f_description_01": "按筛选条件更新的餐厅介绍",
      "_data_stage": "deleting"
    }
  ],
  "failedRows": [],
  "permissionDeniedRows": [],
  "delegatedToTodo": false,
  "delegatedRows": [],
  "mutationAppliedRows": [
    {
      "_uuid": "stykuonikdfl",
      "f_title_01": "Biscotte Restaurant（更新）",
      "f_description_01": "按筛选条件更新的餐厅介绍",
      "_data_stage": "deleting"
    }
  ]
}

如果删除操作需要进入审批流程，delegatedToTodo可能为true。

3.10.7 失败结果

没有删除权限时，接口可能返回HTTP 200的业务失败结果：

{
  "tableName": "articles",
  "success": false,
  "data": [],
  "mutationApplied": false,
  "partialSuccess": false,
  "successCount": 0,
  "failedCount": 1,
  "permissionDeniedCount": 1,
  "successRows": [],
  "failedRows": [
    {
      "_uuid": "stykuonikdfl"
    }
  ],
  "permissionDeniedRows": [
    {
      "_uuid": "stykuonikdfl"
    }
  ]
}

鉴权失败时返回HTTP 400：

{
  "error": {
    "code": 400,
    "message": "key-secret校验未通过"
  }
}