在列表 API 中显示资源的总数信息¶

https://blueprints.launchpad.net/cinder/+spec/add-amount-info-in-list-api

此蓝图建议在 Cinder 的列表 API 中添加总数信息。

问题描述¶

通常需要在 Web 门户的摘要部分显示用户或租户拥有的资源数量，但由于我们引入了分页机制，我们只能获得 {resource}_link，它告诉我们还有更多资源。为了向最终用户显示这种总数，许多云必须收集所有资源，而他们只需要显示资源的首页。

用例¶

主要用例是让管理员或用户无需检索和累积所有资源即可知道他们拥有的资源总数。

提议的变更¶

在列表 API 响应中包含总数信息不仅是 Cinder 或 OpenStack 的要求，也是 REST API 的常见要求，因此了解其他人如何操作可能有助于我们为这种情况设计更好的 API 模型。

Facebook API 在其列表 API 中支持 total_count 属性 [1]。这是他们的 API 响应

{
  "data": [],
  "paging": {},
  "summary": {
    "total_count": 100
  }
}

JSON API 组织添加了一个示例来演示 total-pages 或 count 在其推荐示例中的用法 [2]

{
    "meta": {
        "total-pages": 10,
        "count": 100
    },
    "data": [],
    "links": {
        "self": "",
        "prev": "",
        "next": ""
    }
}

StackExchange API 还在其 Common Wrapper Object 中添加了 total 属性 [3]。这是他们的响应示例
```
{
   "items": [],
   "page": 12,
   "page_size": 100,
   "total": 1200,
}
```

由于我们已经在列表 API 响应中添加了 {resources}_links 属性，因此将数量信息添加到响应中（以卷为例）会更加合理。

{
  "volumes_links": [],
  "volumes": [],
  "count": 100
}

因此，此蓝图建议在我们的列表 API（包括索引和详细信息）中添加新的属性 count。

基于我们当前的分页系统 [4]，如果我们默认将 count 属性添加到我们的响应体中，那么数据库的查询语句将仅为一次查询执行两次，这显然会对性能产生影响。考虑到并非每个请求都需要此信息，需要额外的查询参数才能在列出资源时启用它。

/v3/{tenant_id}/{resource}?with_count=true
/v3/{tenant_id}/{resource}/detail?with_count=true

此外，OpenStack API-WG 也推荐这样做 [5]。

对于第一步，我们仅计划为我们的主要资源添加摘要支持：volumes、snapshots 和 backups。

备选方案¶

针对此需求有几种替代解决方案，我们在此列出并比较它们。

在响应头中添加数量信息
```
X-resource-count: 200
```

缺点是它会给 API 客户带来一些负担，我们没有在响应头中添加有用内容的先例。它也使得文档编写更加困难。

为每个资源添加显式 API

POST: /v3/{tenant_id}/{resources}/action {os-count}

此更改涉及大量的修改并创建多个新的 API。为如此简单的 API 更改添加如此多的 API 是过度设计。

为不同的资源创建一个新的 API

POST: /V3/{tenant_id}/action {os-count}
BODY:
    {
        "resource": "volume",
        "user": "user_1",
        "other_filter": "other_value"
    }

对于此更改，如果最终用户在列出资源时想知道总共有多少资源，则需要进行额外的 API 请求。

数据模型影响¶

无

REST API 影响¶

此更改需要 Microversion 升级。

Cinder 客户端影响¶

所有列表命令都将升级以支持此功能。

安全影响¶

无

通知影响¶

无

其他最终用户影响¶

无

性能影响¶

由于如果使用摘要选项请求列表 API，我们将添加额外的 COUNT() 语句，因此会对这些 API 产生负面性能影响，尤其是在数据库中存在大量数据时。

其他部署者影响¶

无

开发人员影响¶

无

实现¶

负责人¶

主要负责人: tommylikehu(tommylikehu@gmail.com)

工作项¶

在列表 API 中添加摘要选项支持
添加相关的单元测试用例
更新 cinder-client 和 OSC。

依赖项¶

无

测试¶

添加单元测试以涵盖此更改。

文档影响¶

更新 API 文档。

在列表 API 中显示资源的总数信息