开始使用

本章节包含开始使用通用 REST API 的实用指南。

假设我们需要通过 REST API 获取应用程序中有关 users 的信息。

首先，按照 扩展组件安装 章节添加 REST API 组件，然后启动应用程序。

允许用户使用 REST API

当使用 REST API 与应用程序交互时，总是以某一特定用户的身份进行操作。因此，我们需要授予该用户通过 API 访问应用程序的能力。

需要将预定义的 REST: minimal access 角色（编码为 rest-minimal）分配给要使用 API 交互的用户。admin 用户已经具有 system-full-access 角色携带的所有权限，因此无需给 admin 用户分配。

身份验证

示例中，我们将使用 curl 命令行工具与 REST API 交互。

在通过 API 加载数据或给 API 发送数据之前，我们首先需要登录或者说进行 Authentication request（验证请求）。用下面的 cURL 命令完成请求：

curl -X POST http://localhost:8080/oauth/token \
   --basic --user client:secret \
   -H "Content-Type: application/x-www-form-urlencoded" \
   -d "grant_type=password&username=admin&password=admin"
如果是 Windows 系统，需要删除 \ 符号，将命令写成一行。

HTTP 200 表示请求成功，返回体中包含一个 JSON，带有身份验证请求的结果：

HTTP/1.1 200
{
  "access_token": "zmSIwB4_9he68yrNsHC5N1agktA",
  "token_type": "bearer",
  "refresh_token": "Tm3_v0T-eeYS6URZgoi4e_r-ub8",
  "expires_in": 31535999,
  "scope": "rest-api",
  "OAuth2.SESSION_ID": "5C46CDF266E8C8C15372887830B74F59"
}

access_token 属性值是用户 token，可作为请求头中的 Authorization 参数使用进行后续其他请求。Token 作为临时凭证，授予你代表用户访问应用程序的权限。

获取实体列表

使用 access token 就可以继续使用通用 REST API 接口获取用户列表（将 <access_token> 替换成上一步获取到的 token 值）。这里，我们通过 API 获取应用程序中当前所有的用户：

curl -X GET http://localhost:8080/rest/entities/User \
    -H "Authorization: Bearer <access_token>"

响应中包含应用程序中所有的用户：

HTTP/1.1 200
[
  {
    "_entityName": "User",
    "_instanceName": "  [admin]",
    "id": "60885987-1b61-4247-94c7-dff348347f93",
    "version": 1,
    "active": true,
    "username": "admin"
  }
]