REST API

REST API 是数据墙DBW 提供的主要数据访问方式之一。引擎会根据实体配置自动为每个数据库对象生成 RESTful 端点，支持标准的 CRUD 操作和常见的数据查询能力。

端点结构

每个实体会自动获得以下 REST 端点，所有端点统一前缀为 /api：

端点	方法	操作
/api/{entity}	GET	查询记录列表
/api/{entity}/{pk}/{value}	GET	按主键查询单条记录
/api/{entity}	POST	创建新记录
/api/{entity}/{pk}/{value}	PUT	全量替换记录
/api/{entity}/{pk}/{value}	PATCH	更新指定字段
/api/{entity}/{pk}/{value}	DELETE	按主键删除记录

可以通过 rest.path 为实体自定义 REST 路径，支持子目录格式如 "shopping-cart/item"。

查询参数

REST API 支持以下标准 OData 风格查询参数：

参数	用途	示例
$select	选择返回的字段	?$select=id,title
$filter	按条件筛选	?$filter=year ge 1970
$orderby	排序	?$orderby=year desc
$first	每页记录数	?$first=20
$after	分页游标	?$after={token}

筛选支持比较运算符（eq、ne、gt、ge、lt、le）和逻辑组合（and、or）。分页使用游标模式，响应中携带 nextLink 指向下一页。

默认情况下，每次查询最多返回 100 条记录（可通过 runtime.pagination.default-page-size 调整）。使用 $first=-1 可请求配置的最大分页大小。

自增主键的无键更新

当实体的主键全部为自增类型（如 SQL Server 的 IDENTITY 或 PostgreSQL 的 SERIAL）时，可以不指定主键直接发送 PUT 或 PATCH 请求，引擎会自动分配主键：

PUT /api/Book
Content-Type: application/json

{
  "title": "新书",
  "publisher_id": 1234
}

这在数据库使用自增主键的场景下非常实用，避免了先查询再更新的繁琐流程。

子目录路径

实体的 REST 路径支持使用 / 创建子目录风格的 URL 结构：

{
  "entities": {
    "ShoppingCartItem": {
      "source": "dbo.ShoppingCartItem",
      "rest": {
        "path": "shopping-cart/item"
      }
    }
  }
}

配置后端点为 GET /api/shopping-cart/item，适合需要层次化 URL 结构的 API 设计。

响应压缩

引擎支持 HTTP 响应压缩，可在 runtime.compression 中配置：

{
  "runtime": {
    "compression": {
      "level": "optimal"
    }
  }
}

级别	说明
optimal	平衡压缩率和速度（推荐）
fastest	优先速度
none	禁用压缩

响应格式

REST 响应统一为以下 JSON 结构：

{
  "value": [
    { "id": 1, "title": "示例" }
  ],
  "nextLink": "https://host/api/entity?$after=..."
}

无论单条还是多条查询，响应结构保持一致。错误时返回 error 字段，包含 code、message 和 status。

NOTE

按不存在的主键查询时返回 200 OK 和空 value 数组，而非 404。需检查数组是否为空来判断记录是否存在。

存储过程调用

存储过程类型的实体通过 POST /api/{entity} 调用，参数放在请求体中：

POST /api/GetBookById
{
  "id": 1001
}

权限约束

所有 REST 操作都受到实体权限配置的约束。只有被显式授予了对应操作权限的角色才能执行请求。未配置权限的实体拒绝所有访问。

与 OpenAPI 的集成

数据墙DBW 可自动为 REST API 生成 OpenAPI 规范和 Swagger 文档，无需手工维护。生成的规范可以直接导入 Postman、Swagger UI 等工具。