api-sig/guidelines/representation_structure.rst

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:

  {
    "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.