From 49eac625edbdc18c66f968080e9ac77c70f8021a Mon Sep 17 00:00:00 2001
From: Steven Kaufer <kaufer@us.ibm.com>
Date: Thu, 15 Jan 2015 22:14:23 +0000
Subject: [PATCH] Add Resource Counting Guidelines

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
---
 guidelines/counting.rst | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
 create mode 100644 guidelines/counting.rst

diff --git a/guidelines/counting.rst b/guidelines/counting.rst
new file mode 100644
index 0000000..64c516b
--- /dev/null
+++ b/guidelines/counting.rst
@@ -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>
+    }