资源管理 API

资源管理接口用于管理 API 资源及其权限范围（Scope）。资源代表需要保护的 API 服务，Scope 定义了该资源下的细粒度权限。

所有接口均需要管理员令牌认证：Authorization: Bearer <admin_token>

获取资源列表

GET /api/v1/resources

分页获取 API 资源列表。

查询参数：

参数	类型	必填	默认值	说明
page	integer	否	1	页码
page_size	integer	否	20	每页条数

请求示例：

curl -X GET "https://your-domain/api/v1/resources?page=1&page_size=10" \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "data": [
      {
        "id": "res_001",
        "name": "Bookstore API",
        "indicator": "https://api.bookstore.com",
        "access_token_ttl": 3600,
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      }
    ],
    "total": 5,
    "page": 1,
    "page_size": 10
  }
}

---

创建资源

POST /api/v1/resources

创建一个新的 API 资源。

请求体：

字段	类型	必填	默认值	说明
name	string	是	-	资源名称
indicator	string	是	-	资源标识符（通常为 API 的 Base URL），需唯一
access_token_ttl	integer	否	3600	访问令牌有效期（秒）

请求示例：

curl -X POST https://your-domain/api/v1/resources \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bookstore API",
    "indicator": "https://api.bookstore.com",
    "access_token_ttl": 7200
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "res_002",
    "name": "Bookstore API",
    "indicator": "https://api.bookstore.com",
    "access_token_ttl": 7200,
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

错误响应（标识符重复）：

{
  "code": 400,
  "message": "资源标识符已存在",
  "result": ""
}

---

获取资源详情

GET /api/v1/resources/:id

根据资源 ID 获取资源详细信息。

路径参数：

参数	类型	说明
id	string	资源 ID

请求示例：

curl -X GET https://your-domain/api/v1/resources/res_002 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "res_002",
    "name": "Bookstore API",
    "indicator": "https://api.bookstore.com",
    "access_token_ttl": 7200,
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T08:00:00Z"
  }
}

---

更新资源

PATCH /api/v1/resources/:id

更新资源信息。仅传入需要修改的字段。

注意： indicator 字段创建后不可修改。

路径参数：

参数	类型	说明
id	string	资源 ID

请求体：

字段	类型	必填	说明
name	string	否	资源名称
access_token_ttl	integer	否	访问令牌有效期（秒）

请求示例：

curl -X PATCH https://your-domain/api/v1/resources/res_002 \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bookstore API v2",
    "access_token_ttl": 3600
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "res_002",
    "name": "Bookstore API v2",
    "indicator": "https://api.bookstore.com",
    "access_token_ttl": 3600,
    "created_at": "2025-06-15T08:00:00Z",
    "updated_at": "2025-06-15T12:00:00Z"
  }
}

---

删除资源

DELETE /api/v1/resources/:id

删除指定资源及其所有关联的 Scope。

路径参数：

参数	类型	说明
id	string	资源 ID

请求示例：

curl -X DELETE https://your-domain/api/v1/resources/res_002 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": null
}

---

获取资源的 Scope 列表

GET /api/v1/resources/:id/scopes

获取指定资源下的所有权限范围（Scope）。

路径参数：

参数	类型	说明
id	string	资源 ID

请求示例：

curl -X GET https://your-domain/api/v1/resources/res_002/scopes \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "scope_001",
      "name": "read:books",
      "description": "Read books information",
      "resource_id": "res_002",
      "created_at": "2025-06-15T08:00:00Z"
    },
    {
      "id": "scope_002",
      "name": "write:books",
      "description": "Create and update books",
      "resource_id": "res_002",
      "created_at": "2025-06-15T08:00:00Z"
    }
  ]
}

---

创建 Scope

POST /api/v1/resources/:id/scopes

为指定资源创建一个新的权限范围。

路径参数：

参数	类型	说明
id	string	资源 ID

请求体：

字段	类型	必填	说明
name	string	是	Scope 名称（如 read:books），在同一资源下需唯一
description	string	否	Scope 描述

请求示例：

curl -X POST https://your-domain/api/v1/resources/res_002/scopes \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "delete:books",
    "description": "Delete books"
  }'

成功响应：

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "scope_003",
    "name": "delete:books",
    "description": "Delete books",
    "resource_id": "res_002",
    "created_at": "2025-06-15T10:00:00Z"
  }
}

---

删除 Scope

DELETE /api/v1/resources/:id/scopes/:scopeId

删除指定资源下的某个权限范围。

注意： 删除 Scope 后，所有引用该 Scope 的角色将自动取消关联。

路径参数：

参数	类型	说明
id	string	资源 ID
scopeId	string	Scope ID

请求示例：

curl -X DELETE https://your-domain/api/v1/resources/res_002/scopes/scope_003 \
  -H "Authorization: Bearer <admin_token>"

成功响应：

{
  "code": 0,
  "message": "success",
  "result": null
}