AuraBoot
免费开始
English简体中文

REST API

AuraBoot 为所有平台操作提供 RESTful API。Web UI 中可执行的每一项操作 —— 从查询记录到执行 Command —— 都可以通过 API 访问。

认证

所有 API 请求都需要 JWT bearer token。通过调用登录接口获取：

curl -X POST http://localhost:6443/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@auraboot.com",
    "password": "YourPassword"
  }'

响应：

{
  "code": "0",
  "message": "success",
  "data": {
    "jwt": "eyJhbGciOiJIUzI1NiIs...",
    "userId": "1234567890",
    "userPid": "01HXYZ...",
    "username": "admin",
    "tenantId": "1",
    "tenantStatus": "member"
  }
}

在后续所有请求中携带该 token：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Base URL

所有 API 端点均以以下前缀开头：

http://localhost:6443/api

生产环境请替换为你的域名并启用 HTTPS。

响应格式

所有响应都遵循统一的信封格式：

{
  "code": "0",
  "message": "success",
  "data": { ... }
}
字段类型描述
codestring"0" 表示成功，否则为错误码
messagestring可读消息
dataany响应载荷(object、array 或 null)

错误响应使用相同格式并附带非零 code：

{
  "code": "VALIDATION_ERROR",
  "message": "Field 'title' is required",
  "data": null
}

通用约定

以下规则适用于下方每一个端点 —— 接入时请与对应 Spring @RequestParam / @RequestBody 实测核对(红线 §5 禁止凭经验猜参数名)。

必备 Header

Header是否必填说明
Authorization: Bearer <jwt>是除 /api/auth/login 与 /api/health 外的所有端点。
X-Tenant-Id可选覆盖 JWT 解析出的 tenant；服务器强制校验归属，不匹配 → 403 TENANT_FORBIDDEN。
Accept-Language可选BCP-47(en、zh-CN)。驱动响应中的 i18n 解析。
Content-Type: application/jsonPOST/PUT 时必填multipart 上传除外。
X-Idempotent-Key可选命令执行(POST /api/meta/commands/execute/{commandCode})的幂等去重 header;去重窗口 24 小时。也可改用请求体内的 clientRequestId 字段。

列表查询参数

每一个列表端点 —— GET /api/dynamic/{pageKey}/list、dashboard 数据源、审计日志搜索 —— 都使用同一套参数契约。禁止 混用 page / size / pageNum；canonical 名称为：

参数类型默认值说明
pageNumint11-based。
pageSizeint10最大 500。
keywordstring—在 model 可搜索字段上进行全文匹配。
sortFieldstringcreated_at必须是绑定 model 上的字段 code。
sortOrderstringdescasc 或 desc。
filtersJSON array—URL 编码;见下方 Filters 格式。

错误信封

错误共用响应信封;按 code 映射：

codeHTTP含义
0200成功。
VALIDATION_ERROR400字段级错误;data.fieldErrors 为 { fieldCode: message }。
UNAUTHORIZED401JWT 缺失 / 过期。
FORBIDDEN403权限不足。data.permission 列出所需 code。
TENANT_FORBIDDEN403跨 tenant 访问。
NOT_FOUND404资源缺失或已软删除。
IDEMPOTENT_REPLAY200重复 X-Idempotent-Key / clientRequestId;data 为原始结果。
RATE_LIMITED429见 限流。
INTERNAL_ERROR500服务器故障;data.traceId 用于日志关联。

校验错误必定包含按字段的 map，便于 UI 在字段控件上展示错误(绝不能用泛化 banner —— 红线 §2.2)：

{
  "code": "VALIDATION_ERROR",
  "message": "1 validation error",
  "data": { "fieldErrors": { "email": "$i18n:crm.lead.email.duplicate" } }
}

动态 CRUD 端点

列表查询

GET /api/dynamic/{pageKey}/list
参数类型默认值描述
pageNumint1页码(1-based)
pageSizeint10每页记录数(最大 500)
keywordstring—在可搜索字段上的全文检索
sortFieldstringcreated_at排序字段 code
sortOrderstringdescasc 或 desc
filtersJSON—过滤条件数组

Filters 格式

filters 参数接受 JSON 条件数组：

[
  { "fieldName": "status", "operator": "eq", "value": "active" },
  { "fieldName": "created_at", "operator": "gte", "value": "2024-01-01" }
]

支持的 operator：eq、ne、gt、gte、lt、lte、like、in、not_in、is_null、is_not_null。

示例

curl "http://localhost:6443/api/dynamic/crm_lead_list/list?\
pageNum=1&pageSize=20&keyword=acme&\
filters=%5B%7B%22fieldName%22%3A%22status%22%2C%22operator%22%3A%22eq%22%2C%22value%22%3A%22new%22%7D%5D" \
  -H "Authorization: Bearer $TOKEN"

响应：

{
  "code": "0",
  "data": {
    "records": [
      { "id": "1234567890", "lead_name": "Acme Corp", "status": "new", ... }
    ],
    "total": 42,
    "pageNum": 1,
    "pageSize": 20
  }
}

执行 Command

所有写操作都通过同一个端点(commandCode 是路径参数,业务字段放在请求体的 payload 中)：

POST /api/meta/commands/execute/{commandCode}

创建

curl -X POST http://localhost:6443/api/meta/commands/execute/crm:create_lead \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "lead_name": "Jane Smith",
      "email": "jane@example.com",
      "status": "new"
    }
  }'

更新

curl -X POST http://localhost:6443/api/meta/commands/execute/crm:update_lead \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationType": "UPDATE",
    "targetRecordId": "1234567890",
    "payload": {
      "lead_name": "Jane Smith-Updated"
    }
  }'

删除

curl -X POST http://localhost:6443/api/meta/commands/execute/crm:delete_lead \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operationType": "DELETE",
    "targetRecordId": "1234567890"
  }'

单条记录读取

GET /api/dynamic/{pageKey}/{recordId}

其中 recordId 是路径参数。

数据源查询

用于自定义查询(dashboard 与报表使用)：

GET /api/datasource/list?datasourceId={code}&maxItems=200

分页

列表端点返回分页结果。通过 pageNum 与 pageSize 翻页：

第 1 页: pageNum=1&pageSize=20  → 记录 1-20
第 2 页: pageNum=2&pageSize=20  → 记录 21-40

响应中的 total 字段表示匹配总记录数。

限流

API 请求按用户维度限流。默认上限：

端点类型上限
读(list、detail)100 req/min
写(command execute)30 req/min
认证(login)10 req/min

下一步