GET {base} HTTP/1.1
Host: {host}

HTTP/1.1 200 OK
Link: <http://{host}/{base}/hosts>; rel=hosts, <http://{host}/{base}/vms>; rel=vms
Content-Type: application/xml

<api>
    <link rel="hosts" href="{base}/hosts"/>
    <link rel="vms" href="{base}/vms"/>
    ...
    <special_objects>
        <link rel="templates/blank" href="..."/>
        <link rel="tags/root" href="..."/>
    </special_objects>
    <summary>
        <vms>
            <total>10</total>
            <active>3</active>
        </vms>
        <hosts>
            <total>2</total>
            <active>2</active>
        </hosts>
        <users>
            <total>8</total>
            <active>2</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</api>

4.1. Link elements

Access to the Entry Point provides the Link header ^[2] , link elements and URIs for all of the resource collections exposed by the API. Each collection uses a relation type to identify the URI a client needs. The following relation types are available:

Relationship	Description
capabilities	Information about the supported capabilities of the Red Hat Enterprise Virtualization Manager
datacenters	Data centers
clusters	Host clusters
networks	Virtual networks
storagedomains	Storage domains
hosts	Hosts
vms	Virtual machines
templates	Templates
vmpools	Virtual machine pools
roles	Roles
users	Users
domain	Identity domain
tags	Tags
events	Events
statistics	Statistics

Figure 4.1.  The relationship between the API entry point and the resource collections exposed by the API

URIs

All URIs shown in example responses are purely illustrative. The format of all URIs returned by the server is opaque. Clients must navigate to any specific resources through the entry point URI and use the relationship types to access the URIs.

The server may choose to include absolute URIs or absolute paths ^[3] in the link element href attribute, so clients should be prepared to handle either form. Link headers will only contain absolute URIs.

In addition to the literal URIs described above, the Link header also contains a set of URI templates ^[4] , which describe the form of URI used for sending search queries to the collections. Each URI template is identified by a relation type, named according to the convention "collection/search".

URI Templates

The purpose of the URI template is to accept a search expression using the natural HTTP pattern of a query parameter. The client does not require prior knowledge of the URI structure. Thus clients should treat these templates as being opaque and instantiate them via a URI template library such as the Google Code uri-templates Python package or the Apache Abdera support for Java templates.

The following relation types are associated with query URI templates:

Relationship	Description
datacenters/search	Query data centers
clusters/search	Query host clusters
storagedomains/search	Query storage domains
hosts/search	Query hosts
vms/search	Query virtual machines
templates/search	Query templates
vmpools/search	Query virtual machine pools
events/search	Query events
users/search	Query users