资源计数

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

指导

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

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

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

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