Home

Understanding the Abiquo Python client

The idea of this Python client is to be a thin wrapper around the JSON objects and provide a small set of helper methods for the common operations that a consumer of the API will have to perform.

There are two main objects: the Abiquo client, that provides methods to perform HTTP requests against a configured endpoint, and an ObjectDto, that represents a deserialized HTTP response from the Abiquo API.

The use of the Abiquo client is pretty straightforward. Each method (get, put, post, delete) returns a tuple consisting of the response code, and an ObjectDto representing the HTTP deserialized response.

This ObjectDto has the following set of properties and helper methods:

• json - This property holds the raw json response, in case you want to manually read it.
• follow(rel) - This will get the link with the given rel and return a new Abiquo client object pointing at the link's URL, and preconfigured with the accept header taken from the link "type" field. For example, getting the VAPPS in a VDC object could be done as: vdc.follow('virtualappliances').get()
• _extract_link(rel)/_has_link(rel) - Get the link with the given rel.
• put/delete - The are convenient methods that modify the current object. Instead of having to "follow the edit link and put", it's just a shortcut so you can easily modify the fields in the current object and call put on itself (or delete the object itself).
• Helpers for collections - The ObjectDto also implements the iterable interface, so if the returned object is a collection, you can iterate it easily. The client will take care of transparently advancing and retrieving each element of the collection, as well as fetching more pages as needed. For example, the following code will transparently iterate through all the datacenters, fetching any additional pages if needed:

from abiquo.client import Abiquo

api = Abiquo(API_URL, auth=(username, password))
code, datacenters = api.admin.datacenters.get(headers={'accept': 'application/vnd.abiquo.datacenters+json'})
for dc in datacenters:
    pass

The ObjectDto also overrides some python dictionary behaviors to allow using it and accessing the fields in the JSON objects and links in an easy way. You can dome something like:

# Access (read or write) the name of a VDC
vdc.json['name']
vdc.name

# Get the virtual appliances in a VDC
vdc.follow('virtualappliances').get()
vdc.virtualappliances.get()

When using the object dotted notation to access properties of an ObjectDto, it will inspect the JSON to see if there is such a property, and if not, it will try to find a link by rel. The following example shows a small fragment of code that illustrates how to use link nagivation to create and deploy a virtual machine:

import json
from abiquo.client import Abiquo
from abiquo.client import check_response

api = Abiquo(API_URL, auth=(username, password))
vapp_data = '{ ... }'
vm_data = '{ ... }'

# Follow the 'virtualappliances' link of the virtual datacenter and post the vapp object there to create a new one
code, vapp = vdc.virtualappliances.post(data=json.dumps(vapp_data),
    headers={'content-type': 'application/vnd.abiquo.virtualappliance+json',
        'accept': 'application/vnd.abiquo.virtualappliance+json'})
check_response(201, code, vapp)

# Follow the 'virtualmachines' link from the created vapp and post the vm object there
code, vm = vapp.virtualmachines.post(data=json.dumps(vm_data),
    headers={'content-type': 'application/vnd.abiquo.virtualmachine+json',
        'accept': 'application/vnd.abiquo.virtualmachine+json'})
check_response(201, code, vm)

# Follow the "deploy" link on the created VM to execute the deploy action and retrieve the task reference
# In this case we are not sending a body (no need for the 'content-type' header and the right value for the
# accept one is already set by the implicit 'follow' method
code, task_ref = vm.deploy.post()