8.3.6. Sub-Collection Relationships

A sub-collection relationship defines hierarchical link between a resource and a sub-collection. The sub-collection exists, or at least 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.

The API defines a relationship between a resource and a sub-collection using the link rel= attribute:

GET /rhevm-api/{collection}/{resource_id} HTTP/1.1

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

<{resource} id="{resource_id}" href="/rhevm-api/{collection}/{resource_id}">
    ...
    <link rel="{subcollection}"
      href="/rhevm-api/{collection}/{resource_id}/{subcollection}"/>
    ...
</{resource}>

This means an API user queries the sub-collection at /rhevm-api/{collection}/{resource_id}/{subcollection}:

GET /rhevm-api/{collection}/{resource_id}/{subcollection} HTTP/1.1

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

<{subcollection}>
    <{subresource} id="{subresource_id}"
      href="/rhevm-api/{collection}/{resource_id}/{subcollection}/{subresource_id}">
        ...
    </{subresource}>
    ...
</{subcollection}>