资源计数

本文档旨在提供关于在项目的公共 REST API 中返回资源集合总大小的指导；当资源总数可能大于单个响应中枚举的资源数量时，这非常有用。

指导

查询字符串参数 ‘with_count’ 用于指示是否应该从 GET REST API 请求中返回资源的计数。任何等效于 True 的值都表示应该返回计数；相反，任何等效于 False 的值都表示不应该返回计数。

如果缺少 ‘with_count’ 查询字符串参数，服务器仍然可以包含计数；但是，它应该仅在确定计数是微不足道的并且不需要，例如，额外的数据库查询时才这样做。当获取计数可能代价高昂时，只有在明确请求时才应将其包含在内。

在 JSON 响应中，计数值是一个整数，并与顶级属性 ‘count’ 相关联。例如，在检索服务器时，如果提供了 ‘with_count=true’，则应将总计数包含在响应中，如下所示：

{
    "servers": [...],
    "count": <int_count>
}