Page Comparison

...

Introduction

Welcome to the REST API of the Abiquo cloud platform. Yes, the Abiquo API really is a HATEOAS REST API. 

...

In this tutorial you will:

1. Create a VM with the UI and the API

2. Get a VM and deploy it

3. 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: 

1. Private cloud infrastructure 

2. A virtual datacenter with a virtual appliance inside

3. 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: 

  1. Send a GET request with basic authentication to the login resource of your API, for example, https://abiquo.example.com/api/login

  2. Get the token from the X-Abiquo-Token header 

  3. In your request, use the format of Authentication: Token XXXXXXXX

• Basic authentication: in a securely isolated test environment only

  • Use Authentication: Basic XXXXX with the format user:password in base64 encoding
    Or in the request line use the option -u user:password 

  • In your test environment you may also need to add the insecure -k option to the request. 

• 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.

1. Log in to Abiquo and open your browser console to the Network tab

2. Record browser actions

3. Create a VM in the UI. The UI will send a POST request to the API

4. In the browser console, find the POST request

   1. Tips when using Chrome:

      1. 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.

      2. To copy the request directly from the UI, right-click on the request URL and select Copy as cURL and delete UI cache details from the URL before you run it

5. From Headers, Response Headers find the location. This is the VM link where you will send requests to modify the VM 

6. From the Payload, click view source, and right-click and copy, then format with a JSON formatter. This is the VM object that you can modify and use in the next request to create a VM

Screenshot from Chrome: the POST request to create a VM is selected.Image Removed

...

Analyze the post request

This section explains the request to create the VM in a bit more detail.

When you created the VM:

• The UI sent the POST request to the virtualmachines link of the virtual appliance. The link contains the IDs of the virtual datacenter and virtual appliance.

  Code Block
  https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines

  
  

  • You can use this link to create another VM

  • In this case, the ID values are 12 and 4.

• The Request Payload contains the basic VM object with a name and a link to a VM template, and an option to enable remote access to the VM.

  Code Block
  { "name":"vmapihowto", "links":[ { "title":"yVM", "rel":"virtualmachinetemplate", "type":"application/vnd.abiquo.virtualmachinetemplate+json", "href":"https://mjsabiquo.lab.abiquo.com:443/api/admin/enterprises/1/datacenterrepositories/2/virtualmachinetemplates/145" } ], "vdrpEnabled":true }

  
  

  • You can copy this object and modify it to create another VM

• 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.

  Code Block
  https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/304

  
  

  • You can use this link to manage the VM in the API

  • The last element of the URL is the ID of the VM, which has a value of 304.

...

Create a VM using the API

To create a new VM:

1. Create a POST request to the virtualmachines link

2. Add headers to describe your JSON data objects 

   1. The Content-Type header refers to the VM object you are sending. 

   2. The Accept header refers to the API response you will receive

3. Add your authentication (see the Authentication section above)

4. As request data, you can add the VM entity from the previous step and change the name attribute, e.g., change  vmapihowto to vmapihowto2

5. You can use a tool such as jq to format the API response

   Code Block

   curl -X POST 'https://mjsabiquo.lab.abiquo.com/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines' \ -H 'Accept: application/vnd.abiquo.virtualmachine+json;version=6.1' \ -H 'Authorization: Token XXXXXX' \ -H 'Content-Type: application/vnd.abiquo.virtualmachine+json;version=6.1' \ --data-raw '{"name":"vmapihowto2","links":[{"title":"yVM","rel":"virtualmachinetemplate","type":"application/vnd.abiquo.virtualmachinetemplate+json","href":"https://mjsabiquo.lab.abiquo.com:443/api/admin/enterprises/1/datacenterrepositories/2/virtualmachinetemplates/145"}],"vdrpEnabled":true}' \ --insecure --verbose | jq .

   
   

6. Send the POST request 

If the API creates the machine successfully, the response code is 201 and the body contains the VM object.

...

To manage the VM, you will send requests to VM links, so you should now save some links from the VM object. It is also useful to know the ID of the VM in the API.

From the VM object,

• Get the link with a rel key that has a value of edit. Also note that in the example the VM has an id of 305.

  Code Block
  ... { "links":[ ... { "title": "vmapihowto2", "rel": "edit", "type": "application/vnd.abiquo.virtualmachine+json", "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305" }, ...

  
  

• Also get the link with a rel key that has a value of deploy.

  Code Block
  ... { "title": "virtual machine deploy", "rel": "deploy", "type": "application/vnd.abiquo.acceptedrequest+json", "href": "https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305/action/deploy" }, ...

  
  

...

When you've created the VM, return to the UI and you should be able to find the new VM!  Image Removed

...

...

Get the new VM using the API

...

{
   "message":"You can keep track of the progress in the link",
   "links":[
      {
         "title":"status",
         "rel":"status",
         "type":"application/vnd.abiquo.task+json",
         "href":"https://mjsabiquo.lab.abiquo.com:443/api/cloud/virtualdatacenters/12/virtualappliances/4/virtualmachines/305/tasks/d18178fd-6a95-494c-8257-adda5c53f26f"
      }
   ]
}

To check the progress of the deploy, send a GET request to the above link.

Of course, you can also just switch back to the UI and watch the VM deploy!Image Removed

...

...

Conclusion

Congratulations, you have created a VM and deployed a VM with the API.

...

To work through how to modify and delete entities, see Get Started with the Abiquo API part 2.

Related links

• Basic behaviors

• API How Tos

• API reference documentation