Chapter 2. Example

2.1. Access API Entry Point
2.2. List Data Center Collection
2.3. List Host Cluster Collection
2.4. List Logical Networks Collection
2.5. List Host Collection
2.6. Approve Host
2.7. Create NFS Data Storage
2.8. Create NFS ISO Storage
2.9. Attach Storage Domains to Data Center
2.10. Activate Storage Domains
2.11. Create Virtual Machine
2.12. Attach NIC to Virtual Machine
2.13. Attach Storage Disk to Virtual Machine
2.14. Attach ISO Image to Virtual Machine
2.15. Start Virtual Machine
2.16. Check System Events
2.17. Error Handling

This chapter provides an example to demonstrate the REST API's ability to create virtual machine within a basic Red Hat Enterprise Virtualization environment. This example is intended for users with some proficiency with REST architectural style and some experience with Red Hat Enterprise Virtualization infrastructure.

This example requires the following:

A networked installation of Red Hat Enterprise Virtualization Manager;
A networked and configured host containing Red Hat Enterprise Virtualization Hypervisor;
An ISO file containing a desired virtual machine operating system to install. This chapter uses Red Hat Enterprize Linux Server 6 for our installation ISO example; and
Red Hat Enterprise Virtualization Platform's uploader tool to upload your chosen operating system ISO file.

Identifier Codes

Red Hat Enterprise Virtualization Manager generates an opaque identifier code, or id, for each resource. Identifier codes in this example might appear different to the identifier codes in your Red Hat Enterprise Virtualization environment.

2.1. Access API Entry Point

The following request retrieves a representation of the main entry point of the API.

Example 2.1. Access the API entry point

GET /rhevm-api HTTP/1.1
Accept: application/xml

The API returns the following representation:

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

<api>
    <link rel="capabilities" href="/rhevm-api/capabilities"/>
    <link rel="clusters" href="/rhevm-api/clusters"/>
    <link rel="clusters/search" href="/rhevm-api/clusters?search={query}"/>
    <link rel="datacenters" href="/rhevm-api/datacenters"/>
    <link rel="datacenters/search" href="/rhevm-api/datacenters?search={query}"/>
    <link rel="events" href="/rhevm-api/events"/>
    <link rel="events/search" href="/rhevm-api/events?search={query}"/>
    <link rel="hosts" href="/rhevm-api/hosts"/>
    <link rel="hosts/search" href="/rhevm-api/hosts?search={query}"/>
    <link rel="networks" href="/rhevm-api/networks"/>
    <link rel="roles" href="/rhevm-api/roles"/>
    <link rel="storagedomains" href="/rhevm-api/storagedomains"/>
    <link rel="storagedomains/search" href="/rhevm-api/storagedomains?search={query}"/>
    <link rel="tags" href="/rhevm-api/tags"/>
    <link rel="templates" href="/rhevm-api/templates"/>
    <link rel="templates/search" href="/rhevm-api/templates?search={query}"/>
    <link rel="users" href="/rhevm-api/users"/>
    <link rel="groups" href="/rhevm-api/groups"/>
    <link rel="domains" href="/rhevm-api/domains"/>
    <link rel="vmpools" href="/rhevm-api/vmpools"/>
    <link rel="vmpools/search" href="/rhevm-api/vmpools?search={query}"/>
    <link rel="vms" href="/rhevm-api/vms"/>
    <link rel="vms/search" href="/rhevm-api/vms?search={query}"/>
    <special_objects>
        <link rel="templates/blank"
          href="/rhevm-api/templates/00000000-0000-0000-0000-000000000000"/>
        <link rel="tags/root"
          href="/rhevm-api/tags/00000000-0000-0000-0000-000000000000"/>
    </special_objects>
    <system_version revision="0" build="0" minor="0" major="3"/>
    <summary>
        <vms>
            <total>5</total>
            <active>0</active>
        </vms>
        <hosts>
            <total>1</total>
            <active>1</active>
        </hosts>
        <users>
            <total>1</total>
            <active>1</active>
        </users>
        <storage_domains>
            <total>2</total>
            <active>2</active>
        </storage_domains>
    </summary>
</api>

The entry point provides a user with links to the collections in a virtualization environment. The rel= attribute of each collection link provides a reference point for each link. The next step in this example examines the datacenter collection, which is available through the rel="datacenter" link.