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.