Abiquo 5.1
This tutorial describes how to create and deploy a basic VM with the Abiquo cloud platform. It also describes how to retrieve a single entity and a group of entities from the cloud platform.
This document introduces the API from the perspective of the Abiquo user interface (UI).
You can apply the basic general flow from this document 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 from Chrome.
You will need a working Abiquo platform with:
To create the prerequisite entities, you can do the following:
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 blue
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.
https://nardo40.bcn.abiquo.com/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines
In this case, the ID values are 2486 and 2990.
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 the API Location (in the Response headers) and Request Payload 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.
{ "label":"yVM_Abiquo_enterprise", "links":[ { "title":"yVM_Abiquo_enterprise", "rel":"virtualmachinetemplate", "type":"application/vnd.abiquo.virtualmachinetemplate+json", "href":"https://nardo40.bcn.abiquo.com:443/api/admin/enterprises/336/datacenterrepositories/1/virtualmachinetemplates/2" } ], "vdrpEnabled":true }
The Location link shows the VM location in the API, which is the URL of the VM, as shown here.
https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19453
The last element of the URL is the ID of the VM, which has a value of 19453. 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.
https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/
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 "yvm_Abiquo_enterprise" to "yVM_New".
Here we have an example of an API request to create a VM:
curl --verbose -X POST 'https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines' \ -H 'Content-Type: application/vnd.abiquo.virtualmachine+json;version=5.0' \ -H 'Accept: application/vnd.abiquo.virtualmachine+json;version=5.0' \ -u user:password \ -d '{"label":"yVM_New","links":[{"title":"yVM_Abiquo_enterprise","rel":"virtualmachinetemplate","type":"application/vnd.abiquo.virtualmachinetemplate+json","href":"https://nardo40.bcn.abiquo.com:443/api/admin/enterprises/336/datacenterrepositories/1/virtualmachinetemplates/2"}],"vdrpEnabled":true}'
We are working with JSON objects and we specify them with request content 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 19454.
... { "links":[ { "title":"ABQ_2fb11009-8157-4d61-915d-40fa45f440ac", "rel":"edit", "type":"application/vnd.abiquo.virtualmachine+json", "href":"https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454" }, ...
Also note the deploy link.
... { "title":"virtual machine deploy", "rel":"deploy", "type":"application/vnd.abiquo.acceptedrequest+json", "href":"https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/action/deploy" }, ...
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.
curl --verbose 'https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454' \ -H 'Accept: application/vnd.abiquo.virtualmachine+json; version=5.0' \ -u user:password -k
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.
https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines
The response contains metadata about the size of the collection and the default paging links. The following example shows the collection information but we removed the VM links to reduce the size of the example.
To deploy the VM you created, send a POST request to the deploy link of the VM.
curl --verbose -X POST 'https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/action/deploy' \ -u user:password -k
The API will respond with an accepted request object and a link that you can use to check the progress of the deploy.
{ "message":"You can keep track of the progress in the link", "links":[ { "title":"status", "rel":"status", "type":"application/vnd.abiquo.task+json", "href":"https://nardo40.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2486/virtualappliances/2990/virtualmachines/19454/tasks/a975de9c-8558-4487-8f43-153df2d3cb55" } ] }
Of course, you can also switch back to the UI and watch the VM deploy!
Congratulations, you have created a VM and deployed a VM with the API. And you also know how to retrieve an entity and a collection of entities, and you can apply this method to any entity, using the entity link and a GET request.
To work through how to modify and delete entities, see Get Started with the Abiquo API part 2.
Related links