This document introduces the API from the perspective of the Abiquo user interface (UI).
This document describes a basic general flow to help you get started creating a VM and retrieving it, but you can apply the flow to other Abiquo entities.
To follow along with this tutorial, we recommend that you use a Firefox or Chrome browser. The screenshots and instructions here are for Chromium.
You will need a working Abiquo platform with:
You can create this environment in the UI first by following the Abiquo Quick Tutorial. Then add an extra IP address to your private network by following the instructions in Create IP addresses in private networks.
You will need to authenticate with your own credentials as appropriate in your environment. For a complete guide, see Authentication. For this tutorial you could use:
First, create a VM with the UI.
Screenshot from Chrome: the post request to create a VM is highlighted in red.
In Chrome, to display the Method column to easily identify the POST request, right-click on the header row to display the header options list, then select "Method"
To create a VM, the Abiquo UI makes the POST request to the virtualmachines link of the virtual appliance. This link contains the IDs of the virtual datacenter and virtual appliance.
In this case, the ID values are both "2".
To copy a request directly from the UI, right-click on the request URL and select Copy as cURL. Note that you may have to delete UI cache details before you run the cURL.
In your browser console, select the POST request that created the VM and go to the Headers tab.
The following screenshot highlights the Request Payload and the API Location (in the Response headers) of a VM.
The Request Payload is the VM object that the UI sent to create the VM. It is very simple with just a friendly name label (which by default is the VM template name), a template link, plus the default option to enable remote access to the VM. This is one of the simplest data objects that you can use to create a VM.
Click "view source", and copy the request payload. If you format it with a JSON formatter, it should look similar to the following example.
The Location link shows the VM location in the API, which is the URL of the VM, as shown here.
The last element of the URL is the ID of the VM, which has a value of 6. We can use the above link to retrieve this VM.
To retrieve all the VMs in the virtual appliance, you can use the link to virtualmachines, without referring to any specific VM.
These URLs are the API locations of the VMs.
We are now going to create a new VM with a different friendly-name label.
To create the new VM, use the link to virtualmachines from the previous step, and send a POST request with the modified data entity. For example, we could change "yvm2" to "yVM_New".
Here we have an example of an API request to create a VM:
We are working with JSON objects and we specify them in the request headers that start with "-H". The Content-Type header refers to the VM object we are sending. And the Accept header refers to the API response we will receive.
You can also use XML instead of JSON with the Abiquo API and to do this, you would use "+xml" instead of "+json" in all the headers. Abiquo recommends JSON format. There may be some slight differences between the formats, so always retrieve an object in the format you are working with and modify it to ensure the correct data structure.
We specify the virtualmachine media type and the version number.
To control compatibility always specify the version number in your requests because if you do not specify a version, the API will always return the latest one, meaning that after an upgrade to the platform your code may cease to work as intended.
If the API creates the machine successfully, the response body contains the VM object.
From the VM object, note the link with a "rel" value of "edit". Also note that in the example the VM has an "id" of 8.
When you've created the VM, return to the UI and you should be able to find the new VM!
To retrieve the details of the VM you just created, perform a GET request to the edit link of the VM.
The result of this query is a VM data object in JSON format. The expanding section below contains the full request. On a Linux system, to format the response JSON body inline, you could try piping it to jq (with "| jq ."))
To retrieve the collection of VMs in the virtual appliance, send a GET request to the virtualmachines link.
The response contains metadata about the size of the collection and the default paging links.
So that is how you can create a VM and also how you can retrieve entities from the Abiquo API. You can also retrieve any of the related entities and collections from their links with a simple GET request.
To work through how to modify and delete entities, see Get Started with the Abiquo API part 2.