Representational State Transfer (REST) is a design architecture that focuses on resources for a specific service and their representations. A resource representation is a key abstraction of information that corresponds to one specific managed element on a server. A client sends a request to a server element located at a Uniform Resource Identifier (URI) and performs operations with standard HTTP methods, such as GET, POST, PUT, and DELETE. This provides a stateless communication between the client and server where each request acts independently of any other request, and contains all the information necessary to complete the request.

Prerequisites for using the oVirt API:

The oVirt API requires Hypertext Transfer Protocol Secure (HTTPS) ^[1] for secure interaction with client software, such as the SDK and CLI components. This involves obtaining the CA certificate used by the server, and importing it into the certificate store of your client.

Any user with a oVirt Engine account has access to the API. All requests must be authenticated using either OAuth or basic authentication, as described below.

The API uses the type concept to describe the different kinds of objects accepted and returned.

There are three relevant kinds of types:

Many of the types used by the API represent identified objects, objects that have an unique identifier and exist independently of other objects. The types used to describe those objects extend the Identified type, which contains the following set of common attributes:

Objects are the individual instances of the types supported by the API. For example, the virtual machine with identifier 123 is an object of the Vm type.

A collection is a set of objects of the same type.

The state of objects needs to be represented when it is transferred beetween the client and the server. The API supports XML and JSON as the representation of the state of objects, both for input and output.

Services are the parts of the server responsible for retrieving, adding updating, removing and executing actions on the objects supported by the API.

There are two relevant kinds of services:

Each service is accessible via a particular path within the server. For example, the service that manages the collection of virtual machines available in the system is available in the via the path /vms, and the service that manages the virtual machine 123 is available via the path /vms/123.

All kinds of services have a set of methods that represent the operations that they can perform. The services that manage collections of objects usually have the list and add methods. The services that manage specific objects usually have the get, update and remove methods. In addition, services may also have action methods, that represent less common operations. For example, the Vm service has a start method that is used to start a virtual machine.

For the more usual methods there is a direct mapping between the name of the method and the name of the HTTP method:

The path used in the HTTP request is the path of the service, with the /ovirt-engine/api prefix.

For example, the request to list the virtual machines should be like this, using the HTTP GET method and the path /vms:

For action methods the HTTP method is always POST, and the name of the method is added as a suffix to the path. For example, the request to start virtual machine 123 should look like this, using the HTTP POST method and the path /vms/123/start:

Each method has a set of parameters.

Parameters are classified into two categories:

For example, the operation that adds a virtual machine (see here) has three parameters: vm, clone and clone_permissions. The main parameter is vm, as it describes the object that is added. The clone and clone_permissions parameters are secondary parameters.

The main parameter, when used for input, must be included in the body of the HTTP request. For example, when adding a virtual machine, the vm parameter, of type Vm, must be included in the request body. So the complete request to add a virtual machine, including all the HTTP details, must look like this:

When used for output, the main parameters are included in the response body. For example, when adding a virtual machine, the vm parameter will be included in the response body. So the complete response body will look like this:

Secondary parameters are only allowed for input (except for action methods, which are described later), and they must be included as query parameters. For example, when adding a virtual machine with the clone parameter set to true, the complete request must look like this:

Action methods only have secondary parameters. They can be used for input and output, and they should be included in the request body, wrapped with an action element. For example, the action method used to start a virtual machine (see here) has a vm parameter to describe how the virtual machine should be started, and a use_cloud_init parameter to specify if cloud-init should be used to configure the guest operating system. So the complete request to start virtual machine 123 using cloud-init will look like this when using XML:

The list method of some services has a search parameter that can be used to specify search criteria. When used, the server will only return objects within the collection that satisfy those criteria. For example, the following request will return only the virtual machine named myvm:

The API returns references to related objects as links. For example, when a virtual machine is retrieved it contains links to its disk attachments and network interface cards:

The complete description of those linked objects can be retrieved by sending separate requests:

However, in some situations it is more convenient for the application using the API to retrieve the linked information in the same request. This is useful, for example, when the additional network round trips introduce an unacceptable overhead, or when the multiple requests complicate the code of the application in an unacceptable way. For those use cases the API provides a follow parameter that allows the application to retrieve the linked information using only one request.

The value of the follow parameter is a list of strings, separated by commas. Each of those strings is the path of the linked object. For example, to retrieve the disk attachments and the NICs in the example above the request should be like this:

That will return an response like this:

The path to the linked object can be a single word, as in the previous example, or it can be a sequence of words, separated by dots, to request nested data. For example, the previous example used disk_attachments in order to retrieve the complete description of the disk attachments, but each disk attachment contains a link to the disk, which wasn’t followed. In order to also follow the links to the disks, the following request can be used:

That will result in the following response:

The path can be made as deep as needed. For example, to also get the statistics of the disks:

Multiple path elements and multiple paths can be combined. For example, to get the disk attachments and the network interface cards, both with their statistics:

Many of the services that manage a single object provide a reference to a permissions service that manages the permissions assigned to that object. Each permission contains links to the user or group, the role and the object. For example, the permissions assigned to a specific virtual machine can be retrieved sending a request like this:

The response body will look like this:

A permission is added to an object sending a POST request with a permission representation to this service. Each new permission requires a role and a user.

Some errors require further explanation beyond a standard HTTP status code. For example, the API reports an unsuccessful object state update or action with a fault in the response body. The fault contains the reason and detail attributes. For example, when the server receives a request to create a virtual machine without the mandatory name attribute it will respond with the following HTTP response line:

And the following response body:

The following request retrieves a representation of the main entry point for version 4 of the API:

The same request, but using the /v4 URL prefix instead of the Version header:

The same request, using the curl command:

The result is an object of type 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 data center collection, which is available through the datacenters link.

The entry point also contains other data such as product_info, special_objects and summary. This data is covered in chapters outside this example.

oVirt creates a Default data center on installation. This example uses the Default data center as the basis for the virtual environment.

The following request retrieves a representation of the data centers:

The same request, using the curl command:

The result will be a list of objects of type DataCenter:

Note the id of your Default data center. It identifies this data center in relation to other resources of your virtual environment.

The data center also contains a link to the service that manages the storage domains attached to the data center:

That service is used to attach storage domains from the main storagedomains collection, which this example covers later.

oVirt creates a Default hosts cluster on installation. This example uses the Default cluster to group resources in your oVirt environment.

The following request retrieves a representation of the cluster collection:

The same request, using the curl command:

The result will be a list of objects of type Cluster:

Note the id of your Default host cluster. It identifies this host cluster in relation to other resources of your virtual environment.

The Default cluster is associated with the Default data center through a relationship using the id and href attributes of the data_center link:

The networks link is a reference to the service that manages the networks associated to this cluster. The next section examines the networks collection in more detail.

oVirt creates a default ovirtmgmt network on installation. This network acts as the management network for oVirt Engine to access hosts.

This network is associated with the Default cluster and is a member of the Default data center. This example uses the ovirtmgmt network to connect the virtual machines.

The following request retrieves the list of logical networks:

The same request, using the curl command:

The result will be a list of objects of type Network:

The ovirtmgmt network is attached to the Default data center through a relationship using the data center’s id.

The ovirtmgmt network is also attached to the Default cluster through a relationship in the cluster’s network sub-collection.

This example retrieves the list of hosts and shows a host named myhost registered with the virtualization environment:

The same request, using the curl command:

The result will be a list of objects of type Host:

Note the id of your host. It identifies this host in relation to other resources of your virtual environment.

This host is a member of the Default cluster and accessing the nics sub-collection shows this host has a connection to the ovirtmgmt network.

An NFS data storage domain is an exported NFS share attached to a data center and provides storage for virtualized guest images. Creation of a new storage domain requires a POST request, with the storage domain representation included, sent to the URL of the storage domain collection.

You can enable the wipe after delete option by default on the storage domain. To configure this specify wipe_after_delete in the POST request. This option can be edited after the domain is created, but doing so will not change the wipe after delete property of disks that already exist.

The request should be like this:

And the request body should be like this:

The same request, using the curl command:

The server uses host myhost to create a NFS data storage domain called mydata with an export path of mynfs.example.com:/exports/mydata. The API also returns the following representation of the newly created storage domain resource (of type StorageDomain):

An NFS ISO storage domain is a mounted NFS share attached to a data center and provides storage for DVD/CD-ROM ISO and virtual floppy disk (VFD) image files. Creation of a new storage domain requires a POST request, with the storage domain representation included, sent to the URL of the storage domain collection:

The request should be like this:

And the request body should be like this:

The same request, using the curl command:

The server uses host myhost to create a NFS ISO storage domain called myisos with an export path of mynfs.example.com:/exports/myisos. The API also returns the following representation of the newly created storage domain resource (of type StorageDomain):

The following example attaches the mydata and myisos storage domains to the Default data center.

To attach the mydata storage domain, send a request like this:

With a request body like this:

The same request, using the curl command:

To attach the myisos storage domain, send a request like this:

With a request body like this:

The same request, using the curl command:

The following example creates a virtual machine called myvm on the Default cluster using the virtualization environment’s Blank template as a basis. The request also defines the virtual machine’s memory as 512 MiB and sets the boot device to a virtual hard disk.

The request should be contain an object of type Vm describing the virtual machine to create:

And the request body should be like this:

The same request, using the curl command:

The response body will be an object of the Vm type:

The following example creates a virtual network interface to connect the example virtual machine to the ovirtmgmt network.

The request should be like this:

The request body should contain an object of type Nic describing the NIC to be created:

The same request, using the curl command:

The following example creates an 8 GiB copy-on-write disk for the example virtual machine.

The request should be like this:

The request body should be an object of type DiskAttachment describing the disk and how it will be attached to the virtual machine:

The same request, using the curl command:

The storage_domains attribute tells the API to store the disk on the mydata storage domain.

The boot media for the following virtual machine example requires a CD-ROM or DVD ISO image for an operating system installation. This example uses a CentOS 7 image.

ISO images must be available in the myisos ISO domain for the virtual machines to use. You can use ImageTransfers to create an image transfer and ImageTransfer to upload the ISO image.

Once the ISO image is uploaded, an API can be used to request the list of files from the ISO storage domain:

The same request, using the curl command:

The server returns the following list of objects of type File, one for each available ISO (or floppy) image:

An API user attaches the CentOS-7-x86_64-Minimal.iso to the example virtual machine. Attaching an ISO image is equivalent to using the Change CD button in the administration or user portal applications.

The request should be like this:

The request body should be an object of type Cdrom containing an inner file attribute to indicate the identifier of the ISO (or floppy) image:

The same request, using the curl command:

For more details see the documentation of the service that manages virtual machine CD-ROMS.

The virtual environment is complete and the virtual machine contains all necessary components to function. This example starts the virtual machine using the start method.

The request should be like this:

The request body should be like this:

The same request, using the curl command:

The additional request body sets the virtual machine’s boot device to CD-ROM for this boot only. This enables the virtual machine to install the operating system from the attached ISO image. The boot device reverts back to disk for all future boots.