The OpenNebula OCCI API is a RESTful service to create, control and monitor cloud resources based on the latest draft of the OGF OCCI API specification. There are two types of resources that resemble the basic entities managed by the OpenNebula system, namely:

• Pool Resources (PR): Represents a collection of elements owned by a given user. In particular three pool resources are defined: COMPUTES, NETWORKS and STORAGE.
• Entry Resources (ER): Represents a single entry within a given collection: COMPUTE, NETWORK and DISK.

A COMPUTE entry resource can be linked to one or more DISK or NETWORK resources.

The methods associated with each resource type are as follows:

• Pool Resources (PR)
  • GET: to list all the entry resources in that pool resource owned by the user
  • POST: to create a new entry resource

• Entry Resources (ER)
  • GET: to list the information associated with that resource
  • PUT: to update the resource (only supported by the COMPUTE resource)
  • DELETE: to delete the resource

This section describes the XML format used to represent COMPUTE, NETWORK and DISK resources; as well as the collection of them (Pool Resources, PRs).

The root element required for all the PRs is named after the pool name, eg. COMPUTES, NETWORKS or STORAGE (note that XML tags are upper case). No attributes can be defined for the root element.

Each one of ERs in the pool are described by an element (e.g. COMPUTE, NETWORK or DISK) with one attribute:

• href, a URI for the ER

Example:

    <COMPUTES>
        <COMPUTE href="http://www.opennebula.org/compute/234">
        <COMPUTE href="http://www.opennebula.org/compute/432">
        <COMPUTE href="http://www.opennebula.org/compute/123">
    </COMPUTES>

The NETWORK element defines a virtual network that interconnects those COMPUTES with a network interface card attached to that network. The traffic of each network is isolated from any other network, so it constitutes a broadcasting domain.

The following elements can be defined for a NETWORK:

• ID, the uuid of the network
• NAME, describing the network
• ADDRESS, of the network
• SIZE, of the network, defaults to C

Example:

    <NETWORK>
         <ID>123</ID>
         <NAME>BlueNetwork</NAME>
         <ADDRESS>192.168.0.1</ADDRESS>
         <SIZE>C</SIZE>
    </NETWORK>

The DISK element defines a virtual disk that supports a VM block device. The following elements can be defined:

• ID, the uuid of the image
• NAME, describing the image
• SIZE, of the image in MBs
• URL, pointer to the original image

Example:

    <DISK>
        <ID>123</ID>
        <NAME>Ubuntu 9.04 LAMP</NAME>
        <SIZE>2048</SIZE>
        <URL>file:///images/ubuntu/jaunty.img</URL>
    </DISK>

The COMPUTE element defines a virtual machine by specifying its basic configuration attributes such as NIC or DISK. The following elements can be defined:

• ID, the uuid of the virtual machine.
• NAME, describing the virtual machine.
• TYPE, a COMPUTE type specifies a CPU and memory capacity, valid types are small, medium and large.
• STATE, the state of the COMPUTE. This can be changed to
  • stopped
  • suspended
  • resume
  • cancel
  • shutdown
  • done
• DISKS, the block devices attached to the virtual machine. The following devices can be specified:
  • DISK, a block device supported by a previously registered image. The id attribute specifies the image, dev the device to attach the image to.
  • SWAP, a swap device attached to the specified device (dev) with the given size (in MBs).
  • FS, a plain filesystem attached to the specified device (dev) with the given size (in MBs) and format (ext3 and ext2).
• NICS, the network interfaces, defined with a list of NIC elements. Each NIC can have the following attributes:
  • network, the UUID of the network to bind the interface. Use 0 to make this interface attached to the internet.
  • ip, ask for a given IP of the network.

Example:

    <COMPUTE>
        <ID>123AF</ID>
        <NAME>Web Server</NAME>
        <INSTANCE_TYPE>small</INSTANCE_TYPE>
        <STATE>running</STATE>
        <DISKS>
            <DISK image="234" dev="sda1"/>
            <SWAP size="1024" dev="sda2"/>
            <FS size="1024" format="ext3" dev="sda3"/>
        </DISKS>
        <NETWORK>
            <NIC network="4567f" ip="19.12.1.1"/>
            <NIC network="0"/>
        </NETWORK>
    </COMPUTE>

User authentication will be HTTP Basic access authentication to comply with REST philosophy. Authorization will be handled by OpenNebula's user management module, that currently works as:

• There are normal users and one privilege user (known as oneadmin)
• All users can access retrieve information of all PRs
• All users can perform operations over all PRs
• Normal users can perform operations over their ERs, but no over other users'
• Privilege user oneadmin can perform operations over all ERs

The following headers are compulsory:

• Content-Length: The size of the Entity Body in octets
• Content-Type: application/xml

Uploading images needs HTTP multi part support, and also the following header

• Content-Type: multipart/form-data

The OpenNebula Cloud API uses the following subset of HTTP Status codes:

• 200 OK : The request has succeeded. The information returned with the response is dependent on the method used in the request, as follows:
  • GET an entity corresponding to the requested resource is sent in the response
  • POST an entity containing the result of the action
• 201 Created : Request was successful and a new resource has being created
• 202 Accepted : The request has been accepted for processing, but the processing has not been completed
• 204 No Content : The request has been accepted for processing, but no info in the response
• 400 Bad Request : Malformed syntax
• 401 Unauthorized : Bad authentication
• 403 Forbidden : Bad authorization
• 404 Not Found : Resource not found
• 500 Internal Server Error : The server encountered an unexpected condition which prevented it from fulfilling the request.
• 501 Not Implemented : The functionality requested is not supported

The methods specified below are described without taking into account 4xx (can be inferred from authorization information in section above) and 5xx errors (which are method independent). HTTP verbs not defined for a particular entity will return a 501 Not Implemented.

• Base URL : http://www.opennebula.org/compute

• Base URL : http://www.opennebula.org/network

• Base URL : http://www.opennebula.org/storage

All the above resources share the same HTTP verb semantics:

• Base URL : http://www.opennebula.org/network/<net_id>

• Base URL : http://www.opennebula.org/storage/<storage_id>

• Base URL : http://www.opennebula.org/compute/<compute_id>

It is recommended that the server-client communication is performed over HTTPS to avoid sending user authentication information in plain text.

HTTP protocol does not provide means for notification, so this API relies on asynchronous polling to find whether a VM update is successful or not.