678fce5b70
Also, probably worth reviewing this guidelines to see if it reflects the current plans and state of the art. Change-Id: I54bcd7559b4bc35ded5256403c972592c2f27bc9
33 lines
1.3 KiB
ReStructuredText
33 lines
1.3 KiB
ReStructuredText
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>
|
|
}
|