From 1b1bf26bd85e167bbbef7137f62a5e24aa70cd3b Mon Sep 17 00:00:00 2001
From: Shaunak Kashyap <ycombinator@gmail.com>
Date: Tue, 11 Nov 2014 03:58:27 -0800
Subject: [PATCH] Guideline for collection resources' representation structures

By having consistent structures for collection resources'
representations, these representations remain extensible and consumers
of the APIs can utilize common serialization/deserialization logic.

Change-Id: Idf9a5b95622a3537992466515e05b23d329c30f8
---
 guidelines/representation_structure.rst | 52 +++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
 create mode 100644 guidelines/representation_structure.rst

diff --git a/guidelines/representation_structure.rst b/guidelines/representation_structure.rst
new file mode 100644
index 0000000..9c92d32
--- /dev/null
+++ b/guidelines/representation_structure.rst
@@ -0,0 +1,52 @@
+Representation Structure Conventions
+====================================
+
+Singular resources
+------------------
+
+TODO
+
+Collection resources
+--------------------
+
+JSON request and response representations for collection resources should be
+an object that includes a top-level property to encapsulate the collection of
+resources. The value of this property should be a JSON array whose elements are
+the JSON representations of the resources in the collection.
+
+For example, when listing networks using the ``GET /networks`` API,
+
+  - The JSON response representation would be structured as follows:
+
+    .. code-block:: javascript
+
+        {
+          "networks": [
+            {
+              // Properties of network #1
+            },
+            {
+              // Properties of network #2
+            }
+          ]
+        }
+
+*Rationale*: Having JSON collection resource representations be an object
+— as opposed to an array — allows the representation to be extensible. For
+instance, properties that represent collection-level metadata could be
+added at a later time.
+
+Here are some other OpenStack APIs that use this structure:
+
+- `Bulk creating networks <http://developer.openstack.org/api-ref-networking-v2.html#networks>`_,
+  which uses the top-level ``networks`` property in the JSON request and
+  response representations.
+- `Listing stacks <http://developer.openstack.org/api-ref-orchestration-v1.html#stacks>`_,
+  which uses the top-level ``stacks`` property in the JSON response
+  representation.
+- `Listing database instances <http://developer.openstack.org/api-ref-databases-v1.html#Database_Instances>`_,
+  which uses the top-level ``instances`` property in the JSON response
+  representation.
+- `Listing servers <http://developer.openstack.org/api-ref-compute-v2.html#compute_servers>`_,
+  which uses the top-level ``servers`` property in the JSON response
+  representation.