Counting Resources

This topic document serves to provide guidance on returning the total size of a resource collection in a project’s public REST API; this is useful when the total number of resources may be larger than the number of resources being enumerated in a single response.

Guidance

The ‘with_count’ query string parameter is used to indicate if the total count of resources should or should not be returned from a GET REST API request. Any value that equates to True indicates that the count should be returned; conversely, any value that equates to False indicates that the count should not be returned.

If the ‘with_count’ query string parameter is absent, the server may still include the count; however, it should only do so if determining the count is trivial and does not require, for example, an additional database query. When the count is potentially expensive to obtain, it should only be included if it is explicitly requested.

In the JSON reply, the count value is an integer and is associated with the top-level property ‘count’. For example, when retrieving servers, if ‘with_count=true’ is supplied then the total count should be included in the reply as:

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