资源 API

资源接口覆盖设备分组、凭据和备份命令模板。所有请求都需要 X-API-Key，并且资源响应只返回各自 API Schema 声明的字段。

列表接口都支持统一分页参数：普通列表默认 page=1、limit=50，limit 最大为 100。

分组

端点

方法	路径	权限	说明
GET	/api/v1/groups	groups.view	分页查询分组
GET	/api/v1/groups/tree	groups.view	查询完整分组树
GET	/api/v1/groups/{group_id}	groups.view	获取分组详情
POST	/api/v1/groups	groups.create	创建分组，返回 201
PUT	/api/v1/groups/{group_id}	groups.update	更新分组
DELETE	/api/v1/groups/{group_id}	groups.delete	删除分组

查询分组

GET /api/v1/groups?page=1&limit=50

分组列表没有搜索或过滤参数。分组对象字段如下：

字段	类型	说明
id	integer	分组 ID
name	string	分组名称
parent_id	integer/null	父分组 ID
path	string	分组路径，例如 /1/3/
depth	integer	树深度
sort_order	integer	同级排序值
created_at	string	创建时间

查询分组树

GET /api/v1/groups/tree

返回值是分组对象数组，每个节点额外包含递归的 children 数组：

[
  {
    "id": 1,
    "name": "核心机房",
    "parent_id": null,
    "path": "/1/",
    "depth": 0,
    "sort_order": 0,
    "created_at": "2026-08-14T10:00:00",
    "children": [
      {
        "id": 2,
        "name": "接入区",
        "parent_id": 1,
        "path": "/1/2/",
        "depth": 1,
        "sort_order": 0,
        "created_at": "2026-08-14T10:01:00",
        "children": []
      }
    ]
  }
]

创建、更新和删除分组

创建：

POST /api/v1/groups
Content-Type: application/json

{
  "name": "核心机房",
  "parent_id": null
}

name 必填且不能与已有分组重复；parent_id 为 null 表示根分组。

更新：

PUT /api/v1/groups/{group_id}
Content-Type: application/json

{
  "name": "核心机房-01",
  "parent_id": 2
}

当前实现中，name 不提供时保持原值；parent_id 不提供时会按输入模型的默认值 null 处理，即将分组移动到根层级。若要保持原父分组，请显式传入原来的 parent_id。

删除：

DELETE /api/v1/groups/{group_id}

成功响应为 { "status": "success" }。包含子分组或仍被设备使用的分组不能删除。

常见错误码：RESOURCE_GROUP_NAME_EXISTS、RESOURCE_GROUP_NOT_FOUND、RESOURCE_GROUP_HAS_CHILDREN、RESOURCE_GROUP_IN_USE。

凭据

端点

方法	路径	权限	说明
GET	/api/v1/credentials	credentials.view	分页查询凭据
GET	/api/v1/credentials/{credential_id}	credentials.view	获取凭据详情
POST	/api/v1/credentials	credentials.create	创建凭据，返回 201
PUT	/api/v1/credentials/{credential_id}	credentials.update	更新凭据
DELETE	/api/v1/credentials/{credential_id}	credentials.delete	删除凭据

查询凭据

GET /api/v1/credentials?page=1&limit=50

凭据列表没有搜索或过滤参数。成功响应中的凭据对象只包含：

{
  "id": 1,
  "name": "只读网络设备账号",
  "username": "backup-reader",
  "remarks": "仅用于测试环境",
  "created_at": "2026-08-14T10:00:00"
}

password 和 enable_password 永远不会出现在 API 响应中。

创建和更新凭据

创建：

POST /api/v1/credentials
Content-Type: application/json

{
  "name": "只读网络设备账号",
  "username": "backup-reader",
  "password": "replace-me",
  "enable_password": null,
  "remarks": "仅用于测试环境"
}

name 和 username 必填，password、enable_password 和 remarks 可选。密码在服务端加密保存。

更新：

PUT /api/v1/credentials/{credential_id}
Content-Type: application/json

{
  "username": "backup-reader-v2",
  "password": "replace-me"
}

更新字段可选；未提供的字段保持原值。密码字段不会回显，也不要在请求日志、Issue 或自动化平台的公开输出中打印密码。

删除凭据

DELETE /api/v1/credentials/{credential_id}

凭据仍被设备使用时不能删除。常见错误码：RESOURCE_CREDENTIAL_NAME_EXISTS、RESOURCE_CREDENTIAL_NOT_FOUND、RESOURCE_CREDENTIAL_IN_USE。

备份命令模板

端点

方法	路径	权限	说明
GET	/api/v1/templates	templates.view	分页查询模板
GET	/api/v1/templates/{template_id}	templates.view	获取模板详情
POST	/api/v1/templates	templates.create	创建模板，返回 201
PUT	/api/v1/templates/{template_id}	templates.update	更新模板
DELETE	/api/v1/templates/{template_id}	templates.delete	删除模板

创建和更新模板

创建：

POST /api/v1/templates
Content-Type: application/json

{
  "name": "Cisco IOS 默认备份",
  "platform": "cisco_ios",
  "commands": "show running-config"
}

name 和 platform 必填，commands 可选。省略或提交空白命令时，系统会根据平台填充默认命令。

更新：

PUT /api/v1/templates/{template_id}
Content-Type: application/json

{
  "commands": "show running-config\nshow startup-config"
}

未提供的字段保持原值；如果 commands 为空，则会按更新后的平台重新使用默认命令。模板响应字段为 id、name、platform、commands 和 created_at。

commands 是设备上实际执行的命令文本。请根据设备权限和平台要求验证命令，不要把具有修改或破坏性的命令放入备份模板。

删除模板

DELETE /api/v1/templates/{template_id}

成功响应为 { "status": "success" }。模板不存在时返回 RESOURCE_TEMPLATE_NOT_FOUND。