Abiquo 4.6
Introduction
This document introduces the API from the perspective of the Abiquo user interface (UI).
- All Abiquo platform functionality as seen in the UI is also available through the Abiquo REST API.
- The UI runs as a client of the API, using the API to perform actions on the platform.
- Abiquo recommends that before you start working with the API, you should use the Abiquo UI to learn about the features and functionality of the platform. Or at least do the Abiquo Quick Tutorial.
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.
- Replace the URLs in the examples with the URL for your own environment
- We provide example responses in case you are reading this without access to the platform
- Due to release timing, some of the requests examples may be run using different versions and media types may vary slightly
More tutorials of specific use cases are also available in the API Tutorials section of this wiki. For API reference documentation, see https://wiki.abiquo.com/api/latest
Prerequisites
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:
- Cloud infrastructure including a datacenter, rack, and hypervisor host
- A virtual datacenter with a virtual appliance inside
- An Abiquo private network in the virtual datacenter with two IP addresses added to it
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.
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: you could use the token returned in the X-Abiquo-Token header in the format "Authentication: Token XXXXXXXX", replacing XXXXXXXX with the token.
- Basic authentication: in a securely isolated test environment, you could use your user and password, in the format "-u user:password". To use basic authentication, you can add the insecure "-k" option to the request.
- OAuth authentication. See Authentication
Create an entity with the UI
First, create a VM with the UI.
- Open your connection to Abiquo and open your browser console to the Network tab
- Check that the browser is recording actions
- Create a VM in the UI, which will issue a post request to the API
- In the browser console, find the POST request
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.
https://example.com/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines
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.
{
"label":"yvm2",
"links":[
{
"title":"yvm2",
"rel":"virtualmachinetemplate",
"type":"application/vnd.abiquo.virtualmachinetemplate+json",
"href":"https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/2/datacenterrepositories/1/virtualmachinetemplates/86"
}
],
"vdrpEnabled":true
}
The Location link shows the VM location in the API, which is the URL of the VM, as shown here.
https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/6
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.
https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines
These URLs are the API locations of the VMs.
Create an entity through the API
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:
curl --verbose -X POST 'https://mjsabiquo.bcn.abiquo.com/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines' \
-H 'Content-Type: application/vnd.abiquo.virtualmachine+json;version=4.6' \
-H 'Accept: application/vnd.abiquo.virtualmachine+json;version=4.6' \
-u user:password \
-d '{"label":"yVM_New","links":[{"title":"yvm2", "rel":"virtualmachinetemplate", "type":"application/vnd.abiquo.virtualmachinetemplate+json", "href":"https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/2/datacenterrepositories/1/virtualmachinetemplates/86"}],"vdrpEnabled":true}'
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.
...
{
"links":[
{
"href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8",
"type": "application/vnd.abiquo.virtualmachine+json",
"rel": "edit",
"title": "ABQ_06cfadf0-db57-48c5-8f4c-f9fe2ca76c46"
},
...
Display the entity in the UI
When you've created the VM, return to the UI and you should be able to find the new VM!
Retrieve an entity through 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://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8' \
-H 'Accept: application/vnd.abiquo.virtualmachine+json; version=4.6' \
-u admin:xabiquo
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://example.com/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines
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.
Overview
Content Tools
Activity
