The OpenNebula OCCI API is a RESTful service to create, control and monitor cloud resources using an implementation of the OGF OCCI API specification based on the draft 0.8. This implementation also includes some extensions, requested by the community, to support OpenNebula specific functionality. 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: COMPUTE_COLLECTION, NETWORK_COLLECTION and STORAGE_COLLECTION.
• Entry Resources (ER): Represents a single entry within a given collection: COMPUTE, NETWORK and STORAGE.

A COMPUTE entry resource can be linked to one or more STORAGE 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
  • DELETE: to delete the resource

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

You can download the XML Schemas (XSD) following this link

The root element required for all the PRs is named after the pool name, eg. COMPUTE_COLLECTION, NETWORK_COLLECTION or STORAGE_COLLECTION (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 STORAGE) with one attribute:

• href, a URI for the ER

Example:

• Compute Collection

    <COMPUTE_COLLECTION>
        <COMPUTE href="http://www.opennebula.org/compute/310" name="TestVM"/>
        <COMPUTE href="http://www.opennebula.org/compute/432" name="Server1"/>
        <COMPUTE href="http://www.opennebula.org/compute/123" name="Server2"/>
    </COMPUTE_COLLECTION>

• Network Collection

    <NETWORK_COLLECTION>
        <NETWORK href="http://www.opennebula.org/network/310" name="Private_LAN"/>
        <NETWORK href="http://www.opennebula.org/network/432" name="Public_IPS"/>
    </NETWORK_COLLECTION>

• Storage Collection

    <STORAGE_COLLECTION>
        <STORAGE href="http://www.opennebula.org/storage/310" name="Ubuntu10.04"/>
        <STORAGE href="http://www.opennebula.org/storage/432" name="CentOS6"/>
    </STORAGE_COLLECTION>

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 href="http://www.opennebula.org/network/123">
         <ID>123</ID>
         <NAME>BlueNetwork</NAME>
         <ADDRESS>192.168.0.1</ADDRESS>
         <SIZE>C</SIZE>
    </NETWORK>

The STORAGE is a resource containing an operative system or data, to be used as a virtual machine disk:

• ID, the uuid of the image
• NAME, name of the image
• DESCRIPTION, describing the image
• TYPE, type of the image
  • OS: contains a working operative system
  • CDROM: readonly data
  • DATABLOCK: storage for data, which can be accessed and modified from different Computes
• SIZE, of the image in MBs
• FSTYPE, in case of DATABLOCK, the type of filesystem desired

Example:

    <STORAGE href="http://www.opennebula.org/storage/123">
        <ID>123</ID>
        <NAME>Ubuntu Desktop</NAME>
        <DESCRIPTION>UUbuntu 10.04 desktop for students.</DESCRIPTION>
        <TYPE>OS</TYPE>
        <SIZE>2048</SIZE>
    </STORAGE>

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
  • INIT
  • PENDING
  • HOLD
  • ACTIVE
  • STOPPED
  • SUSPENDED
  • DONE
  • FAILED
• DISK, the block devices attached to the virtual machine.
• NIC, the network interfaces.

Example:

    <COMPUTE href="http://www.opennebula.org/compute/32">
        <ID>32</ID>
        <NAME>Web Server</NAME>
        <INSTANCE_TYPE>small</INSTANCE_TYPE>
        <STATE>ACTIVE</STATE>
        <DISK>
            <STORAGE href="http://www.opennebula.org/storage/34" name="Ubuntu10.04"/>
            <TYPE>OS</TYPE>
            <TARGET>hda</TARGET>
            ...
        </DISK>
        <DISK>
            <STORAGE href="http://www.opennebula.org/storage/24" name="testingDB"/>
            <TYPE>CDROM</TYPE>
            <TARGET>hdc</TARGET>
            ...
        </DISK>
        ...
        <NIC>
            <NETWORK href="http://www.opennebula.org/network/12" name="Private_LAN"/>
            <MAC>00:ff:72:31:23:17</MAC>
            <IP>192.168.0.12</IP>
            ...
        </NIC>
        <NIC>
            <NETWORK href="http://www.opennebula.org/network/10" name="Public_IPs"/>
            <MAC>00:ff:72:17:20:27</MAC>
            <IP>192.168.0.25</IP>
            ...
        </NIC>
        ...
    </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.