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 `_, + which uses the top-level ``networks`` property in the JSON request and + response representations. +- `Listing stacks `_, + which uses the top-level ``stacks`` property in the JSON response + representation. +- `Listing database instances `_, + which uses the top-level ``instances`` property in the JSON response + representation. +- `Listing servers `_, + which uses the top-level ``servers`` property in the JSON response + representation.