API 规范
AngusGM 基于 RESTful 设计原则 构建，并严格遵循 OpenAPI 3.0 规范格式。
1. 协议规范
-
必须使用 HTTPS
所有 API 必须通过 HTTPS 提供，以确保数据传输安全。注意：私有部署客户可能未配置安全证书，需要单独处理。
-
API 版本管理
版本号嵌入在 URL 路径中：/api/v1/resource /api/v2/resource
2. 资源命名规范
- 统一使用 小写字母 或 小驼峰命名法 - 示例：
/user /productCategories /orderItems
3. HTTP 方法规范
| 方法 | 描述 | 成功状态码 | 示例 |
|---|---|---|---|
| GET | 检索资源 | 200 | GET /users |
| POST | 创建资源 | 201 | POST /users |
| PUT | 完整替换资源（不存在则创建） | 200 | PUT /users/{id} |
| PATCH | 部分更新资源 | 200 | PATCH /users/{id} |
| DELETE | 删除资源 | 204 | DELETE /users/{id} |
特殊操作模式 - 使用动词/形容词进行颗粒度操作：
PATCH /users/{id}/enabled # 启用用户 POST /orders/{id}/cancel # 取消订单
4. 安全认证
OAuth 2.0 认证 - 受保护的资源需要认证请求头：
Authorization: Bearer <access_token>
5. 请求参数规范
请求头 (Request Headers)
Content-Type: application/json
Accept: application/json
Authorization: Bearer xxxxxxxxxxxx
查询参数 (Query Parameters)
| 参数类型 | 格式示例 | 描述 |
|---|---|---|
| 分页 | ?pageNo=2&pageSize=20 |
页码和每页大小 |
| 排序 | ?orderBy=createdDate&orderSort=DESC |
排序字段和方向 |
| 过滤 | ?status=active&role=admin |
字段过滤条件 |
请求体 (RequestBody - JSON)
{
"name": "张三",
"email": "john@example.com",
"role": "member",
"preferences": {
"notifications": true,
"theme": "dark"
}
}
6. 响应规范
状态码 (Status Codes)
| 状态码 | 含义 |
|---|---|
| 200 | OK - 请求成功 |
| 201 | Created - 资源创建成功 |
| 204 | No Content - 成功，无响应体内容 |
| 400 | Bad Request - 客户端请求错误 |
| 401 | Unauthorized - 未认证 |
| 403 | Forbidden - 权限不足，访问被拒绝 |
| 404 | Not Found - 资源不存在 |
| 429 | Too Many Requests - 请求过于频繁被限流 |
| 500 | Internal Server Error - 服务器内部错误 |
响应体结构 (Response Body Structure)
{
"code": "S",
"msg": "成功",
"data": {
"total": 42,
"list": [
{
"id": "301222970049691648",
"username": "U20250628001287",
"email": "user@example.com"
}
]
},
"datetime": "2025-06-15 14:49:56",
"ext": {}
}
快速入门指南
1. 获取访问令牌 (Access Token)
系统访问令牌 (System Access Token)
适用场景：系统间集成
获取流程：
- 登录 AngusGM 应用。
- 导航至：系统管理 → 系统令牌。
- 创建新令牌：
- 输入令牌名称
- 设置权限范围
- 配置过期时间
- 点击 创建令牌 生成新凭证。
注意：系统令牌拥有完整的 API 权限且无数据范围限制。
用户访问令牌 (User Access Token)
适用场景：用户级别的 API 操作
获取流程：
- 登录 AngusGM 应用。
- 访问：用户个人资料 → 访问令牌。
- 创建新令牌：
- 验证用户密码
- 设置令牌名称
- 配置有效期
- 点击 创建令牌 生成凭证。
注意：用户令牌继承该用户的 API 权限和数据访问范围。
2. API 服务端点 (Service Endpoints)
| 部署类型 | 服务端点 |
|---|---|
| SaaS 云服务版 | https://bj-c1-prod-apis.xcan.cloud/gm |
| 私有部署版 | http://GM_HOST:GM_PORT (默认) |
或通过 GM_APIS_URL_PREFIX 配置 |
3. API 调用示例
curl -i 'https://bj-c1-prod-apis.xcan.cloud/gm/api/v1/user/search?pageNo=1&pageSize=10' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer 7RProMAjgCr40gMgrsnRROvMXHrXrDrzwqo7ti1V2ZXc6bjoWvVEOTkjbQnLAxMTi5fJrnET'
响应示例:
HTTP/1.1 200 OK
Date: Sun, 15 Jun 2025 06:49:56 GMT
Content-Type: application/json
XC-Request-Id: 34acb65c2c484188a2f9f3a3f4ca3d1f
{
"code": "S",
"msg": "Success",
"data": {
"total": "1",
"list": [
{
"id": "301222970049691648",
"username": "U20250628001287",
"fullName": "张三",
"email": "user@example.com",
"createdDate": "2025-06-12 11:19:21"
}
]
},
"datetime": "2025-06-15 14:49:56"
}