openstack/api-sig
Code Issues Proposed changes

Add Resource Counting Guidelines

Browse Source 
Adds a new resource counting guideline document.

Based on ML discussion:
https://www.mail-archive.com/openstack-dev@lists.openstack.org/msg40287.html

Change-Id: Ia4c9381ff9cdb3746e9000d7b472aeaf7a32022a
This commit is contained in:
Steven Kaufer 2015-01-15 22:14:23 +00:00 committed by STEVEN R. KAUFER
parent a1ceb34135
commit 49eac625ed
1 changed files with 32 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
guidelines/counting.rst Normal file
View File

@ -0,0 +1,32 @@
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 then the number of the 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>
}