REST 端点参考
数据墙DBW 根据实体配置自动生成 RESTful 端点。本文档完整描述 REST API 的端点结构、HTTP 方法、查询参数和响应格式。
端点结构
https://{host}/{rest-path}/{entity}| 组成部分 | 说明 | 默认值 |
|---|---|---|
host | 服务主机地址和端口 | localhost:5000 |
rest-path | REST 端点基础路径前缀 | /api（通过 runtime.rest.path 配置） |
entity | 实体名称，区分大小写 | — |
NOTE
所有路径组件和查询参数都区分大小写。
HTTP 方法
每个实体根据其类型和配置支持不同的 HTTP 方法：
| 方法 | 操作 | 表 | 视图 | 存储过程 |
|---|---|---|---|---|
GET | 查询记录 | ✓ | ✓ | ✓（需配置 rest.methods: ["GET"]） |
POST | 创建记录 | ✓ | 若可更新 | ✓（默认方法） |
PUT | 替换记录 | ✓ | 若可更新 | — |
PATCH | 部分更新 | ✓ | 若可更新 | — |
DELETE | 删除记录 | ✓ | 若可更新 | — |
端点 URL 模式
表实体
| URL 模式 | 方法 | 说明 |
|---|---|---|
/{entity} | GET | 查询列表 |
/{entity}/{pk-name}/{pk-value} | GET | 按主键查询单条 |
/{entity} | POST | 创建记录 |
/{entity}/{pk-name}/{pk-value} | PUT | 替换记录 |
/{entity}/{pk-name}/{pk-value} | PATCH | 更新字段 |
/{entity}/{pk-name}/{pk-value} | DELETE | 删除记录 |
复合主键
/{entity}/{pk1-name}/{pk1-value}/{pk2-name}/{pk2-value}例如 GET /api/Inventory/categoryid/3/pieceid/1
视图实体
与表实体相同的 URL 模式。但视图必须指定 key-fields 或 fields[].primary-key，否则按主键查询的 GET 请求会退化为列表查询并返回空数组。
存储过程实体
| URL 模式 | 方法 | 说明 |
|---|---|---|
/{entity} | GET | 参数通过查询字符串传递（需配置 rest.methods: ["GET"]） |
/{entity} | POST | 参数通过 JSON 请求体传递 |
存储过程不支持按主键查询、分页、筛选和排序。
自定义 REST 路径
实体可通过 rest.path 自定义路径，支持正斜杠分隔的层次化 URL：
{ "rest": { "path": "shopping-cart/item" } }生成端点：/api/shopping-cart/item
路由使用最长前缀匹配。验证会阻止路径遍历模式（..）、反斜杠和百分号编码的分隔符。
查询参数
以下参数适用于 GET 请求（集合查询和按主键查询）：
| 参数 | 类型 | 说明 | 示例 |
|---|---|---|---|
$select | string | 选择返回字段，逗号分隔 | ?$select=id,title |
$filter | string | OData 条件筛选 | ?$filter=year ge 2000 |
$orderby | string | 排序，多字段逗号分隔 | ?$orderby=year desc,title asc |
$first | integer | 每页记录数 | ?$first=20 |
$after | string | 分页游标令牌 | ?$after=eyJpZCI6MjB9 |
参数顺序无强制要求，但建议按 $filter → $orderby → $select → $first → $after 的顺序书写以提高可读性。
$filter 运算符
| 运算符 | 含义 | 示例 |
|---|---|---|
eq | 等于 | title eq 'Dune' |
ne | 不等于 | year ne 2000 |
gt | 大于 | pages gt 300 |
ge | 大于等于 | year ge 2000 |
lt | 小于 | pages lt 100 |
le | 小于等于 | year le 2020 |
and | 逻辑与 | year ge 2000 and pages gt 300 |
or | 逻辑或 | title eq 'Dune' or title eq 'Foundation' |
not | 逻辑非 | not year lt 2000 |
contains | 字符串包含 | contains(title,'Dune') |
startswith | 字符串开头 | startswith(title,'The') |
endswith | 字符串结尾 | endswith(title,'Wakes') |
字符串值使用单引号，数字直接书写。括号控制优先级：(year ge 2000 or title eq 'Dune') and pages gt 300。
URL 编码：空格编码为 %20，单引号编码为 %27。大多数 HTTP 客户端自动处理编码。
请求体格式
POST（创建）
{
"id": 100,
"title": "新书",
"year": 2024,
"pages": 280
}PUT（替换）
请求体必须包含所有非空列。省略必填列会导致 400 Bad Request。
PATCH（部分更新）
请求体只需包含要更新的字段。未传字段保持原值。
request-body-strict 行为
当 runtime.rest.request-body-strict 为 true（默认）时：
- 请求体中不存在于数据库表的字段 →
400 Bad Request - URL 路径中已包含的主键字段不应出现在请求体中
设为 false 时忽略多余字段。
响应格式
成功响应（200/201）
{
"value": [
{ "id": 1, "title": "示例" }
],
"nextLink": "http://host/api/entity?$after=..."
}| 字段 | 说明 | 出现条件 |
|---|---|---|
value | 记录数组 | 始终存在 |
nextLink | 下一页 URL | 有更多分页数据时 |
空结果
{ "value": [] }不存在主键的表实体按主键查询返回 200 + 空数组，而非 404。视图未指定主键时同样返回空数组。
错误响应
{
"error": {
"code": "Not Found",
"message": "No item found with primary key id = 999",
"status": 404
}
}| 字段 | 说明 |
|---|---|
error.code | 错误代码字符串 |
error.message | 人类可读的错误描述 |
error.status | HTTP 状态码 |
HTTP 状态码
| 状态码 | 场景 |
|---|---|
200 OK | 成功查询、更新操作完成 |
201 Created | 成功创建记录（POST） |
204 No Content | 成功删除记录 |
400 Bad Request | 请求参数或请求体格式错误、字段不存在、request-body-strict 拒绝多余字段 |
401 Unauthorized | JWT 令牌无效或过期 |
403 Forbidden | 当前角色无权执行该操作 |
404 Not Found | PUT/PATCH 带 If-Match: * 且记录不存在 |
下一步
- OpenAPI 参考 — OpenAPI 规范和 Swagger UI。
- HTTP If-Match — 控制更新行为的条件头。
- HTTP Location — 创建操作的位置响应头。