Get Started with the Abiquo API
- MS (Unlicensed)
Introduction
Welcome to the REST API of the Abiquo cloud platform. Yes, the Abiquo API really is a HATEOAS REST API.
So there are links everywhere, for navigation, to perform actions, and even to define the configuration of cloud entities.
Fortunately, the Abiquo UI is a client of the Abiquo public REST API, so it's easy to look in your browser tools and find out how the UI performs any API request.
In this tutorial you will:
- Create a VM with the UI and the API
- Get a VM and deploy it
- Get a group of VMs with the API
Requirements
You will need to be familiar with your browser tools. We used Google Chrome.
To complete this tutorial and part 2, you will need a working Abiquo platform with:
- private cloud infrastructure
- a virtual datacenter with a virtual appliance inside
- an Abiquo private network in the virtual datacenter with two IP addresses in it
To become familiar with the UI and create the required entities:
- If your test environment already has infrastructure, work through the Abiquo quick walkthrough of private cloud
- If your test environment does not have infrastructure, work through the Abiquo Quick Tutorial
Authentication
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:
- Token authentication:
- Send a GET request with basic authentication to the login resource of your API, for example, https://abiquo.example.com/api/login
- Get the token from the X-Abiquo-Token header
- In your request, use the format "Authentication: Token XXXXXXXX"
- Basic authentication: in a securely isolated test environment only
- Use "Authentication: Basic XXXXX" with the password in base64 encoding
Or in the request line use the format "-u user:password". - In your test environment you may also need to add the insecure "-k" option to the request.
- Use "Authentication: Basic XXXXX" with the password in base64 encoding
- OAuth authentication. See Authentication
Create a VM with the UI and obtain the POST request
Create a VM with the UI to obtain the API method link and data object.
- Log in to Abiquo and open your browser console to the Network tab
- Record browser actions
- Create a VM in the UI, which will issue a POST request to the API
In the browser console, find the POST request
Chrome tips
- 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 copy the request directly from the UI, right-click on the request URL and select "Copy as cURL". (Delete UI cache details from the URL before you run the cURL!)
Screenshot from Chrome: the POST request to create a VM is highlighted in blue
Analyse the POST request
To create a VM, the Abiquo UI makes the POST request to the virtualmachines link of the virtual appliance entity, sending a basic VM object.
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, which are important parts of the request.
To copy the Request payload, click "view source", and copy, then format with a JSON formatter.
The UI sent the POST request to the virtualmachines link. It contains the IDs of the virtual datacenter and virtual appliance.
https://linatest.bcn.abiquo.com/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines
In this case, the ID values are 42 and 110.
The Request Payload contains the basic VM object with a label (friendly name) and a link to a VM template, and an option to enable remote access to the VM.
{ "label":"yVM_mj", "links":[ { "title":"yVM_mj", "rel":"virtualmachinetemplate", "type":"application/vnd.abiquo.virtualmachinetemplate+json", "href":"https://linatest.bcn.abiquo.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520" } ], "vdrpEnabled":true }After the POST request is successful, the Location link, which you can obtain from the Request headers is the URL of the VM in the API.
https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1918
The last element of the URL is the ID of the VM, which has a value of 1918.
Create a VM using the API
To create a new VM:
- Create a POST request to the virtualmachines link
Add appropriate headers to describe your JSON data objects. The Content-Type header refers to the VM object we are sending. And the Accept header refers to the API response we will receive.
Specify the media type and version number otherwise you may be surprised!
- Use authentication (see the Authentication section above)
- As request data, add the VM entity from the previous step and change the label attribute, e.g. change "yVM_mj" to "yVM_mj_2".
For example:
curl -X POST 'https://linatest.bcn.abiquo.com/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines' \
-H 'Accept: application/vnd.abiquo.virtualmachine+json;version=5.2' \
-H 'Authorization: Token XXXXXXXX' \
-H 'Content-Type: application/vnd.abiquo.virtualmachine+json;version=5.2' \
--data-raw '{"label":"yVM_mj_2","links":[{"title":"yVM_mj","rel":"virtualmachinetemplate","type":"application/vnd.abiquo.virtualmachinetemplate+json","href":"https://linatest.bcn.abiquo.com:443/api/admin/enterprises/1/datacenterrepositories/7/virtualmachinetemplates/520"}],"vdrpEnabled":true}' \
--insecure --verbose | jq .
In this case we will use "jq" to format the response.
Send your POST request. If the API creates the machine successfully, the response body contains the VM object.
Obtain VM links
From the VM object, get the link with a "rel" value of "edit". Also note that in the example the VM has an "id" of 19454.
...
{
"links":[
{
"title": "ABQ_6b2d0d93-7f23-4a78-af5f-a9398be58773",
"rel": "edit",
"type": "application/vnd.abiquo.virtualmachine+json",
"href": "https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920"
},
...
Also get the deploy link.
...
{
"title": "virtual machine deploy",
"rel": "deploy",
"type": "application/vnd.abiquo.acceptedrequest+json",
"href": "https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/action/deploy"
},
...
Display the VM in the UI
When you've created the VM, return to the UI and you should be able to find the new VM!
Get the new VM using the API
To retrieve the details of the VM you just created, perform a GET request to the edit link of the VM.
curl --verbose 'https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920' \ -H 'Accept: application/vnd.abiquo.virtualmachine+json; version=5.2' \ -u user:password -k | jq .
The result of this query is a VM data object in JSON format.
Get a group of VMs with the API
To retrieve the collection of VMs in the virtual appliance, send a GET request to its virtualmachines link.
https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines
The response contains metadata about the size of the collection and the default paging links. (We removed the VM links to reduce the size of the example).
Deploy your VM
To deploy the VM you created, send a POST request to the deploy link of the VM.
curl --verbose -X POST 'https://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/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://linatest.bcn.abiquo.com:443/api/cloud/virtualdatacenters/42/virtualappliances/110/virtualmachines/1920/tasks/140e0136-0ca2-4251-bee8-9656a23ea70f"
}
]
}
Of course, you can also switch back to the UI and watch the VM deploy!
Conclusion
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
Copyright © 2006-2022, Abiquo Holdings SL. All rights reserved