Representation Structure Conventions

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.
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.