7.3.4.  Sub-Collection Relationships

A sub-collection relationship defines a hierarchical link between a resource and a sub-collection. The sub-collection exists or has some meaning in the context of a parent resource. For example, a virtual machine contains network interfaces, which means the API maps the relationship between the virtual machine resource and the network interfaces sub-collection.
Sub-collections are used to model the following relationships types:
  • 1:N mappings, where mapped resources are dependent on a parent resources. Without the parent resource, the dependent resource cannot exist. For example, the link between a virtual machine and its disk resources.
  • 1:N mappings, where mapped resources exist independently from parent resources but data is still associated with the relationship. For example, the link between a network and a cluster.
  • N:M mappings, where one mapped resources only belongs to one parent resource. For example, the link between a storage domain and a data center.
The API defines a relationship between a resource and a sub-collection using the link rel= attribute:
GET /api/collection/resource_id HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<resource id="resource_id" href="/api/collection/resource_id">
    ...
    <link rel="subcollection"
      href="/api/collection/resource_id/subcollection"/>
    ...
</resource>
The API user now queries the sub-collection.
GET /api/collection/resource_id/subcollection HTTP/1.1
Accept: application/xml

HTTP/1.1 200 OK
Content-Type: application/xml

<subcollection>
    <subresource id="subresource_id"
      href="/api/collection/resource_id/subcollection/subresource_id">
        ...
    </subresource>
    ...
</subcollection>