Get Started with the Abiquo API

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. In fact, the UI runs as a client of the API, meaning that it uses the API to perform actions on the platform. For this reason Abiquo recommends that before you start working with the API, you should work with 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 with a VM, 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 examples 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.

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

Create an entity 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: the post request to create a VM is highlighted in red.

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. As the original screenshot from the previous step was lost, we are now working with a different ID of 26 for the virtual datacenter and 37 for the virtual appliance.

https://example.com/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines

If you send a GET request to the virtualmachines link, the response is a list of VMs in the virtual appliance. By default, the response is in JSON format.

The body of the response is a collection of VM objects. Each VM contains a collection of links. For each link, the value of the "rel" (relation) attribute indicates what kind of object you can retrieve from the link, or what kind of action you can perform with it. For example, your can retrieve the VM owner, virtual datacenter, resources, and so on.

Click here to expand...

{
    "totalSize": 1,
    "links": [
        {
            "rel": "first",
            "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines?limit=25&by=name&asc=true"
        },
        {
            "rel": "last",
            "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines?startwith=0&limit=25&by=name&asc=true"
        }
    ],
    "collection": [
        {
            "id": 198,
            "uuid": "66052b57-f2b7-4da9-8f9e-e4d9877b89c4",
            "name": "ABQ_66052b57-f2b7-4da9-8f9e-e4d9877b89c4",
            "label": "yVM",
            "description": "A virtual machine",
            "cpu": 1,
            "ram": 48,
            "vdrpEnabled": true,
            "vdrpPort": 0,
            "idState": 1,
            "state": "NOT_ALLOCATED",
            "idType": 0,
            "type": "MANAGED",
            "highDisponibility": 0,
            "password": "48ZbXVj2",
            "monitored": false,
            "protected": false,
            "variables": {},
            "creationTimestamp": 1536228360000,
            "backuppolicies": [],
            "generateGuestInitialPassword": false,
            "natrules": [],
            "iconUrl": "https://upload.wikimedia.org/wikipedia/commons/a/af/Tux.png",
            "links": [
                {
                    "title": "ABQ_66052b57-f2b7-4da9-8f9e-e4d9877b89c4",
                    "rel": "edit",
                    "type": "application/vnd.abiquo.virtualmachine+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198"
                },
                {
                    "title": "Accounting department",
                    "rel": "enterprise",
                    "type": "application/vnd.abiquo.enterprise+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4"
                },
                {
                    "title": "Cloud Admin",
                    "rel": "user",
                    "type": "application/vnd.abiquo.user+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/users/4"
                },
                {
                    "title": "kvmvdc",
                    "rel": "virtualdatacenter",
                    "type": "application/vnd.abiquo.virtualdatacenter+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26"
                },
                {
                    "title": "vapp_kvmvdc",
                    "rel": "virtualappliance",
                    "type": "application/vnd.abiquo.virtualappliance+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37"
                },
                {
                    "title": "metadata",
                    "rel": "metadata",
                    "type": "application/vnd.abiquo.metadata+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/metadata"
                },
                {
                    "title": "vlan network configurations",
                    "rel": "configurations",
                    "type": "application/vnd.abiquo.virtualmachinenetworkconfigurations+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/network/configurations"
                },
                {
                    "title": "nics",
                    "rel": "nics",
                    "type": "application/vnd.abiquo.nics+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/network/nics"
                },
                {
                    "title": "disks",
                    "rel": "harddisks",
                    "type": "application/vnd.abiquo.harddisks+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/storage/disks"
                },
                {
                    "title": "NOT_ALLOCATED",
                    "rel": "state",
                    "type": "application/vnd.abiquo.virtualmachinestate+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/state"
                },
                {
                    "title": "virtual machine undeploy",
                    "rel": "undeploy",
                    "type": "application/vnd.abiquo.acceptedrequest+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/action/undeploy"
                },
                {
                    "title": "virtual machine deploy",
                    "rel": "deploy",
                    "type": "application/vnd.abiquo.acceptedrequest+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/action/deploy"
                },
                {
                    "title": "virtual machine reset",
                    "rel": "reset",
                    "type": "application/vnd.abiquo.acceptedrequest+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/action/reset"
                },
                {
                    "title": "virtual machine snapshot",
                    "rel": "instance",
                    "type": "application/vnd.abiquo.acceptedrequest+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/action/instance"
                },
                {
                    "title": "remote access",
                    "rel": "rdpaccess",
                    "type": "application/vnd.abiquo.virtualmachineconsole+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/config/rdpaccess"
                },
                {
                    "title": "tasks",
                    "rel": "tasks",
                    "type": "application/vnd.abiquo.tasks+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/tasks"
                },
                {
                    "title": "firewalls",
                    "rel": "firewalls",
                    "type": "application/vnd.abiquo.links+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/firewalls"
                },
                {
                    "title": "load balancers",
                    "rel": "loadbalancers",
                    "type": "application/vnd.abiquo.loadbalancers+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/loadbalancers"
                },
                {
                    "title": "request on demand backup",
                    "rel": "requestbackup",
                    "type": "application/vnd.abiquo.ondemandbackup+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/backup/action/request"
                },
                {
                    "title": "request a restore of a backup",
                    "rel": "requestrestore",
                    "type": "application/vnd.abiquo.restore+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/backup/action/restore"
                },
                {
                    "title": "move VM to a virtual appliance",
                    "rel": "vappmove",
                    "type": "application/vnd.abiquo.links+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/action/vappmove"
                },
                {
                    "title": "volumes",
                    "rel": "volumes",
                    "type": "application/vnd.abiquo.volumes+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/storage/volumes"
                },
                {
                    "diskControllerType": "IDE",
                    "diskLabel": "Hard disk 1",
                    "length": "64",
                    "title": "1766a14a-6f5d-47ae-aa1d-47809a25315e",
                    "rel": "disk0",
                    "type": "application/vnd.abiquo.harddisk+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/disks/215"
                },
                {
                    "title": "Default Tier",
                    "rel": "datastoretier0",
                    "type": "application/vnd.abiquo.datastoretier+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/locations/10/datastoretiers/3"
                },
                {
                    "title": "protect",
                    "rel": "protect",
                    "type": "text/plain",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/action/protect"
                },
                {
                    "title": "unprotect",
                    "rel": "unprotect",
                    "type": "text/plain",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/action/unprotect"
                },
                {
                    "title": "metricsmetadata",
                    "rel": "metricsmetadata",
                    "type": "application/vnd.abiquo.metricsmetadata+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/metrics"
                },
                {
                    "title": "enablemonitoring",
                    "rel": "enablemonitoring",
                    "type": "",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/enablemonitoring"
                },
                {
                    "title": "collectd",
                    "rel": "collectd",
                    "type": "application/json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/metrics/collectd"
                },
                {
                    "title": "alarmssearch",
                    "rel": "alarmssearch",
                    "type": "application/vnd.abiquo.alarms+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/alarms"
                },
                {
                    "title": "clone",
                    "rel": "clone",
                    "type": "application/vnd.abiquo.virtualmachinecloneoptions+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/action/clone"
                },
                {
                    "title": "KVM",
                    "rel": "hypervisortype",
                    "type": "application/vnd.abiquo.hypervisortype+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/config/hypervisortypes/KVM"
                },
                {
                    "title": "yVM",
                    "rel": "virtualmachinetemplate",
                    "type": "application/vnd.abiquo.virtualmachinetemplate+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/datacenterrepositories/10/virtualmachinetemplates/243"
                },
                {
                    "title": "Others",
                    "rel": "category",
                    "type": "application/vnd.abiquo.category+json",
                    "href": "https://mjsabiquo.bcn.abiquo.com:443/api/config/categories/1"
                }
            ]
        }
    ],
    "duplicatedvms": []
}

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–just a "friendly" name label (which by default is the 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 from there you can copy the request payload. You can format it with a JSON formatter. After formatting, it should look something like this.

{
   "label":"yVM",
   "links":[
      {
         "title":"yVM",
         "rel":"virtualmachinetemplate",
         "type":"application/vnd.abiquo.virtualmachinetemplate+json",
         "href":"https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/datacenterrepositories/10/virtualmachinetemplates/243"
      }
   ],
   "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/26/virtualappliances/37/virtualmachines/198

This VM has an "id" or identifier value of "198". We can use the above link to retrieve the VM.

Or if we wish to retrieve all the VMs, we will use a link to virtualmachines, without referring to any specific VM.

https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines

Create an entity through the API

We are now going to modify the data entity from the previous step and create a new VM with a different friendly-name label. For example, we can change "yVM_MJ" to "yVM_New".

To create the new VM in the same virtual appliance, use the link to virtualmachines from the previous step and send POST request with the modified data entity.

Remember that you will need to authenticate with your own credentials according to your environment. See Authentication. If you are using an isolated test environment and basic authentication as shown in this example, then you may wish to add the insecure "-k" option.

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/26/virtualappliances/37/virtualmachines' \
 -H 'Content-Type: application/vnd.abiquo.virtualmachine+json;version=4.4' \
 -H 'Accept: application/vnd.abiquo.virtualmachine+json;version=4.4'  \
 -u admin:xabiquo \
 -d '{"label":"yVM_New","links":[{"title":"yVM","rel":"virtualmachinetemplate","type":"application/vnd.abiquo.virtualmachinetemplate+json","href":"https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/datacenterrepositories/10/virtualmachinetemplates/243"}],"vdrpEnabled":true}'

As the response shows, we are working with JSON objects and we specify them in the request headers 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 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. 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 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 199.

...
{  
   "links":[
      {
         "title":"ABQ_f26a16fb-d732-4d73-9bb6-0dbc34cd3a31",
         "rel":"edit",
         "type":"application/vnd.abiquo.virtualmachine+json",
         "href":"https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199"
      },
...

When you return to the UI, you should be able to find the new VM. Congratulations! That was way too easy, wasn't it?

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/26/virtualappliances/37/virtualmachines/199 \
     -H "Accept: application/vnd.abiquo.virtualmachine+json; version=4.4" \
	 -u user:password

The result of this query is a VM data object in JSON format. The expanding section below contains the full request.

(Please note that there may be some variation between the JSON and XML representations of the same object due to the API framework, so if you wish to work with an XML object, perform a separate query with the Accept mediatype set to xml to retrieve it. On a Linux system, to format the response body inline, you could try piping to jq (with | jq .))

Click here to expand...

* Connected to mjsabiquo.bcn.abiquo.com (10.60.13.180) port 443 (#0)
* Server auth using Basic with user 'admin'
> GET /api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199 HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.35.0
> Host: mjsabiquo.bcn.abiquo.com
> Accept: application/vnd.abiquo.virtualmachine+json; version=4.4
> 
< HTTP/1.1 200 200
< Date: Thu, 06 Sep 2018 10:36:01 GMT
* Server Apache is not blacklisted
< Server: Apache
< Set-Cookie: ABQSESSIONID=2099046286284344125; Max-Age=1800; Expires=Thu, 06-Sep-2018 11:06:01 GMT; Path=/; Secure; HttpOnly
< X-Abiquo-Token: b1bdc4461de17670c503e3330f6571fdbc1fe9c7f3aef72a0ab59a58ac053bfb
< Content-Type: application/vnd.abiquo.virtualmachine+json; version=4.4
< Transfer-Encoding: chunked
< 
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0{ [data not shown]
100  7894    0  7894    0     0  17277      0 --:--:-- --:--:-- --:--:-- 17273
* Connection #0 to host mjsabiquo.bcn.abiquo.com left intact
{
  "links": [
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199",
      "type": "application/vnd.abiquo.virtualmachine+json",
      "rel": "edit",
      "title": "ABQ_f26a16fb-d732-4d73-9bb6-0dbc34cd3a31"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4",
      "type": "application/vnd.abiquo.enterprise+json",
      "rel": "enterprise",
      "title": "Accounting department"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/users/1",
      "type": "application/vnd.abiquo.user+json",
      "rel": "user",
      "title": "Cloud Administrator"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26",
      "type": "application/vnd.abiquo.virtualdatacenter+json",
      "rel": "virtualdatacenter",
      "title": "kvmvdc"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37",
      "type": "application/vnd.abiquo.virtualappliance+json",
      "rel": "virtualappliance",
      "title": "vapp_kvmvdc"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metadata",
      "type": "application/vnd.abiquo.metadata+json",
      "rel": "metadata",
      "title": "metadata"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/network/configurations",
      "type": "application/vnd.abiquo.virtualmachinenetworkconfigurations+json",
      "rel": "configurations",
      "title": "vlan network configurations"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/network/nics",
      "type": "application/vnd.abiquo.nics+json",
      "rel": "nics",
      "title": "nics"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/storage/disks",
      "type": "application/vnd.abiquo.harddisks+json",
      "rel": "harddisks",
      "title": "disks"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/state",
      "type": "application/vnd.abiquo.virtualmachinestate+json",
      "rel": "state",
      "title": "NOT_ALLOCATED"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/undeploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "undeploy",
      "title": "virtual machine undeploy"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/deploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "deploy",
      "title": "virtual machine deploy"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/reset",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "reset",
      "title": "virtual machine reset"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/instance",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "instance",
      "title": "virtual machine snapshot"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/config/rdpaccess",
      "type": "application/vnd.abiquo.virtualmachineconsole+json",
      "rel": "rdpaccess",
      "title": "remote access"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/tasks",
      "type": "application/vnd.abiquo.tasks+json",
      "rel": "tasks",
      "title": "tasks"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/firewalls",
      "type": "application/vnd.abiquo.links+json",
      "rel": "firewalls",
      "title": "firewalls"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/loadbalancers",
      "type": "application/vnd.abiquo.loadbalancers+json",
      "rel": "loadbalancers",
      "title": "load balancers"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/backup/action/request",
      "type": "application/vnd.abiquo.ondemandbackup+json",
      "rel": "requestbackup",
      "title": "request on demand backup"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/backup/action/restore",
      "type": "application/vnd.abiquo.restore+json",
      "rel": "requestrestore",
      "title": "request a restore of a backup"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/vappmove",
      "type": "application/vnd.abiquo.links+json",
      "rel": "vappmove",
      "title": "move VM to a virtual appliance"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/storage/volumes",
      "type": "application/vnd.abiquo.volumes+json",
      "rel": "volumes",
      "title": "volumes"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/disks/216",
      "type": "application/vnd.abiquo.harddisk+json",
      "rel": "disk0",
      "title": "35a20d65-ff7f-4f65-8207-45751fa4e400",
      "length": "64",
      "diskLabel": "Hard disk 1",
      "diskControllerType": "IDE"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/locations/10/datastoretiers/3",
      "type": "application/vnd.abiquo.datastoretier+json",
      "rel": "datastoretier0",
      "title": "Default Tier"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/protect",
      "type": "text/plain",
      "rel": "protect",
      "title": "protect"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/unprotect",
      "type": "text/plain",
      "rel": "unprotect",
      "title": "unprotect"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metrics",
      "type": "application/vnd.abiquo.metricsmetadata+json",
      "rel": "metricsmetadata",
      "title": "metricsmetadata"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/enablemonitoring",
      "type": "",
      "rel": "enablemonitoring",
      "title": "enablemonitoring"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metrics/collectd",
      "type": "application/json",
      "rel": "collectd",
      "title": "collectd"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/alarms",
      "type": "application/vnd.abiquo.alarms+json",
      "rel": "alarmssearch",
      "title": "alarmssearch"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/clone",
      "type": "application/vnd.abiquo.virtualmachinecloneoptions+json",
      "rel": "clone",
      "title": "clone"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/config/hypervisortypes/KVM",
      "type": "application/vnd.abiquo.hypervisortype+json",
      "rel": "hypervisortype",
      "title": "KVM"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/datacenterrepositories/10/virtualmachinetemplates/243",
      "type": "application/vnd.abiquo.virtualmachinetemplate+json",
      "rel": "virtualmachinetemplate",
      "title": "yVM"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/config/categories/1",
      "type": "application/vnd.abiquo.category+json",
      "rel": "category",
      "title": "Others"
    }
  ],
  "iconUrl": "https://upload.wikimedia.org/wikipedia/commons/a/af/Tux.png",
  "natrules": [],
  "generateGuestInitialPassword": false,
  "backuppolicies": [],
  "creationTimestamp": 1536229326000,
  "variables": {},
  "protected": false,
  "vdrpEnabled": true,
  "ram": 48,
  "cpu": 1,
  "description": "A virtual machine",
  "label": "yVM_New",
  "name": "ABQ_f26a16fb-d732-4d73-9bb6-0dbc34cd3a31",
  "uuid": "f26a16fb-d732-4d73-9bb6-0dbc34cd3a31",
  "id": 199,
  "vdrpPort": 0,
  "idState": 1,
  "state": "NOT_ALLOCATED",
  "idType": 0,
  "type": "MANAGED",
  "highDisponibility": 0,
  "password": "F8CYQsk4",
  "monitored": false
}

Modify an entity through the API

Because the VM entity is a special case, we are going to look at two types of modifications: configuring a VM and changing the state of a VM.

But for most entities you can simply retrieve a data object with a GET request, modify the data object, and then perform a PUT request.

When you edit the data object, take care not to accidentally remove any links because you could accidentally remove a disk or a NIC or perform some other unintended action!

To add a NIC to the VM, we are going to first perform the steps using the UI, in order to obtain information about the data object.

Configure the VM to add a NIC through the UI

Now we will add a network interface card (NIC) with an IP address in a private network to the first VM we created.

If your VM is deployed and it doesn't have network hot-reconfigure, then shut it down
Open the browser console at the Network tab and record actions
Edit the VM, drag and drop an IP, and save the VM
Examine the PUT request and look for the link to the NIC and expand it. It will probably be at the end of the links section.

At the top of the Request Payload section, click "view source". Copy the source, format it, and select the link to the NIC and copy it. After formatting, it will look something like this.

      {
         "title":"privateip",
         "rel":"nic0",
         "type":"application/vnd.abiquo.privateip+json",
         "href":"https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips/143"
      }

We will use this type of NIC link in the next step.

Add a NIC to the VM through the API

Now we are going to add a NIC to the second VM. To do this, we need to identify the second private IP that we created for this tutorial.

So we perform a GET request to retrieve all the IP addresses on the same network used above.

So we will use the part of the URL that refers to the IPs of the private network, which just means removing the identifier of the IP from the IP link.

https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips

You could just open this link in your browser where you are using the UI, or perform a curl request from the command line, for example.

curl --verbose https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips \
     -H "Accept: application/vnd.abiquo.privateips+json; version=4.4" \
	 -u user:password | jq .

In our response body, there are 3 IP addresses: the gateway and two IP addresses we created specifically for this exercise.

Click here to expand...

> GET /api/cloud/virtualdatacenters/26/privatenetworks/34/ips HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.35.0
> Host: mjsabiquo.bcn.abiquo.com
> Accept: application/vnd.abiquo.privateips+json; version=4.4
> 
< HTTP/1.1 200 200
< Date: Thu, 06 Sep 2018 12:25:06 GMT
* Server Apache is not blacklisted
< Server: Apache
< Set-Cookie: ABQSESSIONID=5089683228809279597; Max-Age=1800; Expires=Thu, 06-Sep-2018 12:55:07 GMT; Path=/; Secure; HttpOnly
< X-Abiquo-Token: b1bdc4461de17670c503e3330f6571fd51f3154c9e1a2ecd86f463ce3cc8acd2
< Content-Type: application/vnd.abiquo.privateips+json; version=4.4
< Transfer-Encoding: chunked
< 
{ [data not shown]
100  3012    0  3012    0     0   8563      0 --:--:-- --:--:-- --:--:--  8581
* Connection #0 to host mjsabiquo.bcn.abiquo.com left intact
{
  "collection": [
    {
      "links": [
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34",
          "type": "application/vnd.abiquo.vlan+json",
          "rel": "privatenetwork",
          "title": "default_private_network"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips/141",
          "type": "application/vnd.abiquo.privateip+json",
          "rel": "self",
          "title": "privateip"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "rel": "virtualdatacenter",
          "title": "kvmvdc"
        }
      ],
      "available": true,
      "ipv6": false,
      "networkName": "default_private_network",
      "name": "525400512A90_host",
      "mac": "52:54:00:51:2A:90",
      "ip": "192.168.0.1",
      "id": 141
    },
    {
      "links": [
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34",
          "type": "application/vnd.abiquo.vlan+json",
          "rel": "privatenetwork",
          "title": "default_private_network"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips/143",
          "type": "application/vnd.abiquo.privateip+json",
          "rel": "self",
          "title": "privateip"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "rel": "virtualdatacenter",
          "title": "kvmvdc"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37",
          "type": "application/vnd.abiquo.virtualappliance+json",
          "rel": "virtualappliance",
          "title": "vapp_kvmvdc"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198",
          "type": "application/vnd.abiquo.virtualmachine+json",
          "rel": "virtualmachine",
          "title": "ABQ_66052b57-f2b7-4da9-8f9e-e4d9877b89c4"
        }
      ],
      "id": 143,
      "ip": "192.168.0.2",
      "mac": "52:54:00:4A:8A:C3",
      "name": "5254004A8AC3_host",
      "networkName": "default_private_network",
      "ipv6": false,
      "usedBy": "ABQ_66052b57-f2b7-4da9-8f9e-e4d9877b89c4",
      "available": true
    },
    {
      "links": [
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34",
          "type": "application/vnd.abiquo.vlan+json",
          "rel": "privatenetwork",
          "title": "default_private_network"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips/217",
          "type": "application/vnd.abiquo.privateip+json",
          "rel": "self",
          "title": "privateip"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "rel": "virtualdatacenter",
          "title": "kvmvdc"
        }
      ],
      "available": true,
      "ipv6": false,
      "networkName": "default_private_network",
      "name": "525400D72B9E_host",
      "mac": "52:54:00:D7:2B:9E",
      "ip": "192.168.0.3",
      "id": 217
    }
  ],
  "links": [
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips?limit=25&by=ip&asc=true",
      "rel": "first"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips?startwith=0&limit=25&by=ip&asc=true",
      "rel": "last"
    }
  ],
  "totalSize": 3
}

In the above example, the IP that is being used on a VM has a link to that VM.

Hint: to only retrieve IPs that are available for use, you can use the request parameter "free=true", as follows.

https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips?free=true

The available IP that we will use has the identifier "217".

And the link we need from this IP object is the link with a "rel" value of "self".

        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips/217",
          "type": "application/vnd.abiquo.privateip+json",
          "rel": "self",
          "title": "privateip"
        }

To add it to the VM, we just need to change "self" to "nicX", where "X" represents the number of the new NIC in the VM. So if there are no NICs on the machine, we will add "nic0" as shown here.

        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips/217",
          "type": "application/vnd.abiquo.privateip+json",
          "rel": "nic0",
          "title": "privateip"
        }

Remember that when you add this NIC to the end of the links section, you must add a comma first, after the previous item. And as this will be the last link, remember to remove the comma after it.

So here is an example of the request body that would be used to update our second VM, with the nic0 link at the end of the links section.

Click here to expand...

{
  "links": [
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199",
      "type": "application/vnd.abiquo.virtualmachine+json",
      "rel": "edit",
      "title": "ABQ_f26a16fb-d732-4d73-9bb6-0dbc34cd3a31"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4",
      "type": "application/vnd.abiquo.enterprise+json",
      "rel": "enterprise",
      "title": "Accounting department"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/users/1",
      "type": "application/vnd.abiquo.user+json",
      "rel": "user",
      "title": "Cloud Administrator"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26",
      "type": "application/vnd.abiquo.virtualdatacenter+json",
      "rel": "virtualdatacenter",
      "title": "kvmvdc"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37",
      "type": "application/vnd.abiquo.virtualappliance+json",
      "rel": "virtualappliance",
      "title": "vapp_kvmvdc"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metadata",
      "type": "application/vnd.abiquo.metadata+json",
      "rel": "metadata",
      "title": "metadata"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/network/configurations",
      "type": "application/vnd.abiquo.virtualmachinenetworkconfigurations+json",
      "rel": "configurations",
      "title": "vlan network configurations"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/network/nics",
      "type": "application/vnd.abiquo.nics+json",
      "rel": "nics",
      "title": "nics"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/storage/disks",
      "type": "application/vnd.abiquo.harddisks+json",
      "rel": "harddisks",
      "title": "disks"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/state",
      "type": "application/vnd.abiquo.virtualmachinestate+json",
      "rel": "state",
      "title": "NOT_ALLOCATED"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/undeploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "undeploy",
      "title": "virtual machine undeploy"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/deploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "deploy",
      "title": "virtual machine deploy"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/reset",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "reset",
      "title": "virtual machine reset"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/instance",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "instance",
      "title": "virtual machine snapshot"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/config/rdpaccess",
      "type": "application/vnd.abiquo.virtualmachineconsole+json",
      "rel": "rdpaccess",
      "title": "remote access"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/tasks",
      "type": "application/vnd.abiquo.tasks+json",
      "rel": "tasks",
      "title": "tasks"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/firewalls",
      "type": "application/vnd.abiquo.links+json",
      "rel": "firewalls",
      "title": "firewalls"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/loadbalancers",
      "type": "application/vnd.abiquo.loadbalancers+json",
      "rel": "loadbalancers",
      "title": "load balancers"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/backup/action/request",
      "type": "application/vnd.abiquo.ondemandbackup+json",
      "rel": "requestbackup",
      "title": "request on demand backup"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/backup/action/restore",
      "type": "application/vnd.abiquo.restore+json",
      "rel": "requestrestore",
      "title": "request a restore of a backup"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/vappmove",
      "type": "application/vnd.abiquo.links+json",
      "rel": "vappmove",
      "title": "move VM to a virtual appliance"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/storage/volumes",
      "type": "application/vnd.abiquo.volumes+json",
      "rel": "volumes",
      "title": "volumes"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/disks/216",
      "type": "application/vnd.abiquo.harddisk+json",
      "rel": "disk0",
      "title": "35a20d65-ff7f-4f65-8207-45751fa4e400",
      "length": "64",
      "diskLabel": "Hard disk 1",
      "diskControllerType": "IDE"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/locations/10/datastoretiers/3",
      "type": "application/vnd.abiquo.datastoretier+json",
      "rel": "datastoretier0",
      "title": "Default Tier"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/protect",
      "type": "text/plain",
      "rel": "protect",
      "title": "protect"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/unprotect",
      "type": "text/plain",
      "rel": "unprotect",
      "title": "unprotect"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metrics",
      "type": "application/vnd.abiquo.metricsmetadata+json",
      "rel": "metricsmetadata",
      "title": "metricsmetadata"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/enablemonitoring",
      "type": "",
      "rel": "enablemonitoring",
      "title": "enablemonitoring"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metrics/collectd",
      "type": "application/json",
      "rel": "collectd",
      "title": "collectd"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/alarms",
      "type": "application/vnd.abiquo.alarms+json",
      "rel": "alarmssearch",
      "title": "alarmssearch"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/clone",
      "type": "application/vnd.abiquo.virtualmachinecloneoptions+json",
      "rel": "clone",
      "title": "clone"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/config/hypervisortypes/KVM",
      "type": "application/vnd.abiquo.hypervisortype+json",
      "rel": "hypervisortype",
      "title": "KVM"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/datacenterrepositories/10/virtualmachinetemplates/243",
      "type": "application/vnd.abiquo.virtualmachinetemplate+json",
      "rel": "virtualmachinetemplate",
      "title": "yVM"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/config/categories/1",
      "type": "application/vnd.abiquo.category+json",
      "rel": "category",
      "title": "Others"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips/217",
      "type": "application/vnd.abiquo.privateip+json",
      "rel": "nic0",
      "title": "privateip"
    }
  ],
  "iconUrl": "https://upload.wikimedia.org/wikipedia/commons/a/af/Tux.png",
  "natrules": [],
  "generateGuestInitialPassword": false,
  "backuppolicies": [],
  "creationTimestamp": 1536229326000,
  "variables": {},
  "protected": false,
  "vdrpEnabled": true,
  "ram": 48,
  "cpu": 1,
  "description": "A virtual machine",
  "label": "yVM_New",
  "name": "ABQ_f26a16fb-d732-4d73-9bb6-0dbc34cd3a31",
  "uuid": "f26a16fb-d732-4d73-9bb6-0dbc34cd3a31",
  "id": 199,
  "vdrpPort": 0,
  "idState": 1,
  "state": "NOT_ALLOCATED",
  "idType": 0,
  "type": "MANAGED",
  "highDisponibility": 0,
  "password": "F8CYQsk4",
  "monitored": false
}

Send a PUT request to update the whole VM, including all the links. As the VM object is quite large, instead of adding it to the -d option between single quotation marks, you can save it to a file, for example, "VMnic.json", and then use the @ notation to reference the file in the cURL.

curl --verbose -X PUT "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199" \
	 -H "Content-Type: application/vnd.abiquo.virtualmachine+json; version=4.4" \
     -H "Accept: application/vnd.abiquo.acceptedrequest+json; version=4.4" \
	 -u user:password \
 	 -d @VMnic.json

The full text of the response object is shown in the expanding section below.

If the request is successful, the response status and message will be "204 No content".

In the UI, when you select the VM, and open the control panel in the Network tab, the NIC should display.

This expanding section contains the full request with the VM object embedded in it.

Click here to expand...

curl --verbose -X PUT "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199" \
	 -H "Content-Type: application/vnd.abiquo.virtualmachine+json; version=4.4" \
     -H "Accept: application/vnd.abiquo.acceptedrequest+json; version=4.4" \
	 -u user:password \
 	 -d '{
  "links": [
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199",
      "type": "application/vnd.abiquo.virtualmachine+json",
      "rel": "edit",
      "title": "ABQ_f26a16fb-d732-4d73-9bb6-0dbc34cd3a31"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4",
      "type": "application/vnd.abiquo.enterprise+json",
      "rel": "enterprise",
      "title": "Accounting department"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/users/1",
      "type": "application/vnd.abiquo.user+json",
      "rel": "user",
      "title": "Cloud Administrator"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26",
      "type": "application/vnd.abiquo.virtualdatacenter+json",
      "rel": "virtualdatacenter",
      "title": "kvmvdc"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37",
      "type": "application/vnd.abiquo.virtualappliance+json",
      "rel": "virtualappliance",
      "title": "vapp_kvmvdc"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metadata",
      "type": "application/vnd.abiquo.metadata+json",
      "rel": "metadata",
      "title": "metadata"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/network/configurations",
      "type": "application/vnd.abiquo.virtualmachinenetworkconfigurations+json",
      "rel": "configurations",
      "title": "vlan network configurations"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/network/nics",
      "type": "application/vnd.abiquo.nics+json",
      "rel": "nics",
      "title": "nics"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/storage/disks",
      "type": "application/vnd.abiquo.harddisks+json",
      "rel": "harddisks",
      "title": "disks"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/state",
      "type": "application/vnd.abiquo.virtualmachinestate+json",
      "rel": "state",
      "title": "NOT_ALLOCATED"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/undeploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "undeploy",
      "title": "virtual machine undeploy"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/deploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "deploy",
      "title": "virtual machine deploy"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/reset",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "reset",
      "title": "virtual machine reset"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/instance",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "instance",
      "title": "virtual machine snapshot"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/config/rdpaccess",
      "type": "application/vnd.abiquo.virtualmachineconsole+json",
      "rel": "rdpaccess",
      "title": "remote access"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/tasks",
      "type": "application/vnd.abiquo.tasks+json",
      "rel": "tasks",
      "title": "tasks"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/firewalls",
      "type": "application/vnd.abiquo.links+json",
      "rel": "firewalls",
      "title": "firewalls"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/loadbalancers",
      "type": "application/vnd.abiquo.loadbalancers+json",
      "rel": "loadbalancers",
      "title": "load balancers"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/backup/action/request",
      "type": "application/vnd.abiquo.ondemandbackup+json",
      "rel": "requestbackup",
      "title": "request on demand backup"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/backup/action/restore",
      "type": "application/vnd.abiquo.restore+json",
      "rel": "requestrestore",
      "title": "request a restore of a backup"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/vappmove",
      "type": "application/vnd.abiquo.links+json",
      "rel": "vappmove",
      "title": "move VM to a virtual appliance"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/storage/volumes",
      "type": "application/vnd.abiquo.volumes+json",
      "rel": "volumes",
      "title": "volumes"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/disks/216",
      "type": "application/vnd.abiquo.harddisk+json",
      "rel": "disk0",
      "title": "35a20d65-ff7f-4f65-8207-45751fa4e400",
      "length": "64",
      "diskLabel": "Hard disk 1",
      "diskControllerType": "IDE"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/locations/10/datastoretiers/3",
      "type": "application/vnd.abiquo.datastoretier+json",
      "rel": "datastoretier0",
      "title": "Default Tier"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/protect",
      "type": "text/plain",
      "rel": "protect",
      "title": "protect"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/unprotect",
      "type": "text/plain",
      "rel": "unprotect",
      "title": "unprotect"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metrics",
      "type": "application/vnd.abiquo.metricsmetadata+json",
      "rel": "metricsmetadata",
      "title": "metricsmetadata"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/enablemonitoring",
      "type": "",
      "rel": "enablemonitoring",
      "title": "enablemonitoring"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/metrics/collectd",
      "type": "application/json",
      "rel": "collectd",
      "title": "collectd"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/alarms",
      "type": "application/vnd.abiquo.alarms+json",
      "rel": "alarmssearch",
      "title": "alarmssearch"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/199/action/clone",
      "type": "application/vnd.abiquo.virtualmachinecloneoptions+json",
      "rel": "clone",
      "title": "clone"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/config/hypervisortypes/KVM",
      "type": "application/vnd.abiquo.hypervisortype+json",
      "rel": "hypervisortype",
      "title": "KVM"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/4/datacenterrepositories/10/virtualmachinetemplates/243",
      "type": "application/vnd.abiquo.virtualmachinetemplate+json",
      "rel": "virtualmachinetemplate",
      "title": "yVM"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/config/categories/1",
      "type": "application/vnd.abiquo.category+json",
      "rel": "category",
      "title": "Others"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/privatenetworks/34/ips/217",
      "type": "application/vnd.abiquo.privateip+json",
      "rel": "nic0",
      "title": "privateip"
    }
  ],
  "iconUrl": "https://upload.wikimedia.org/wikipedia/commons/a/af/Tux.png",
  "natrules": [],
  "generateGuestInitialPassword": false,
  "backuppolicies": [],
  "creationTimestamp": 1536229326000,
  "variables": {},
  "protected": false,
  "vdrpEnabled": true,
  "ram": 48,
  "cpu": 1,
  "description": "A virtual machine",
  "label": "yVM_New",
  "name": "ABQ_f26a16fb-d732-4d73-9bb6-0dbc34cd3a31",
  "uuid": "f26a16fb-d732-4d73-9bb6-0dbc34cd3a31",
  "id": 199,
  "vdrpPort": 0,
  "idState": 1,
  "state": "NOT_ALLOCATED",
  "idType": 0,
  "type": "MANAGED",
  "highDisponibility": 0,
  "password": "F8CYQsk4",
  "monitored": false
}'

Power actions on a VM

Before you begin this section, deploy a VM through the user interface.

To perform a power action (except for reset) on a VM using the API:

Perform a GET request to obtain the VM object and find the VM state link
Create a virtualmachinestate object
Send a PUT request to the VM state link

The VM state link is a link in the VM object with the "rel" attribute set to state. The "title" attribute contains the current state. You can send a PUT request of a virtualmachine state object to the link (in the "href" attribute) to change the state of the VM.

        {
            "title": "ON",
            "rel": "state",
            "type": "application/vnd.abiquo.virtualmachinestate+json",
            "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198/state"
        },

Examples of virtualmachinestate objects

Hard power off
```
{"state": "OFF"}
```

Graceful shutdown

{"state": "OFF", "gracefulShutdown": true}

Power on
```
{"state": "ON"}
```
Pause
```
{"state": "PAUSED"}
```

Example of VM hard power off via API

To hard power off a VM using the API, perform a request like the one shown below.

Click here to show or hide the request example

cURL:

curl -X PUT http://localhost:9000/api/cloud/virtualdatacenters/2205/virtualappliances/1080/virtualmachines/1121/state \ 
	 -H 'Accept:application/vnd.abiquo.acceptedrequest+json; version=4.2' \ 
	 -H 'Content-Type:application/vnd.abiquo.virtualmachinestate+json; version=4.2' \ 
	 -d @requestpayload.json \ 
	 -u user:password --verbose

Success status code: 202

Request payload:

{
  "state": "OFF", 
  "links": []
}

Response payload:

{
  "message": "You can keep track of the progress in the link", 
  "links": [
    {
      "href": "http://localhost:9009/api/cloud/virtualdatacenters/2205/virtualappliances/1080/virtualmachines/1121/tasks/1fd663d5-1e66-4443-b94c-f78d13c9e62f", 
      "rel": "status"
    }
  ]
}

The API will return a link where you can monitor the progress of this operation.

Example of failed graceful shutdown

To perform a graceful shutdown, your VM will need to have guest extensions installed on it. After an operation completes, you can view the status of the task by going to the link in the accepted request link of the response. In this case, the graceful shutdown was not supported and failed.

Click here to show or hide the request example

{
   "links":[
      {
         "rel":"self",
         "href":"https://38testing.bcn.abiquo.com:443/api/cloud/virtualdatacenters/55/virtualappliances/200/virtualmachines/1763/tasks/8812ddf4-a372-40af-81ee-5f5d1e53454c"
      },
      {
         "rel":"parent",
         "href":"https://38testing.bcn.abiquo.com:443/api/cloud/virtualdatacenters/55/virtualappliances/200/virtualmachines/1763/tasks"
      },
      {
         "rel":"acknowledge",
         "href":"https://38testing.bcn.abiquo.com:443/api/cloud/virtualdatacenters/55/virtualappliances/200/virtualmachines/1763/tasks/8812ddf4-a372-40af-81ee-5f5d1e53454c/action/ack"
      },
      {
         "title":"cloudadmin",
         "rel":"user",
         "type":"application/vnd.abiquo.user+json",
         "href":"https://38testing.bcn.abiquo.com:443/api/admin/enterprises/74/users/17"
      },
      {
         "title":"ABQ_5e57c34d-5dcb-482b-be0f-a78931f4abd0",
         "rel":"virtualmachine",
         "type":"application/vnd.abiquo.virtualmachine+json",
         "href":"https://38testing.bcn.abiquo.com:443/api/cloud/virtualdatacenters/55/virtualappliances/200/virtualmachines/1763"
      }
   ],
   "taskId":"8812ddf4-a372-40af-81ee-5f5d1e53454c",
   "userId":"17",
   "type":"SHUTDOWN",
   "ownerId":"1763",
   "state":"FINISHED_UNSUCCESSFULLY",
   "creationTimestamp":1458647896,
   "timestamp":1458647897,
   "jobs":{
      "links":[
      ],
      "collection":[
         {
            "links":[
            ],
            "id":"8812ddf4-a372-40af-81ee-5f5d1e53454c.191e44d9-74fa-453a-b7e0-596237618fcf",
            "parentTaskId":"8812ddf4-a372-40af-81ee-5f5d1e53454c",
            "type":"SHUTDOWN",
            "description":"Shutdown task's shutdown on virtual machine with id 1763",
            "state":"FAILED",
            "rollbackState":"ROLLBACK_DONE",
            "creationTimestamp":1458647896,
            "timestamp":1458647897
         }
      ]
   }
}

Reset a VM using the API

To reset a VM using the API, use a POST request to the reset action link.

Click here to expand...

cURL:

curl -X POST http://localhost:9000/api/cloud/virtualdatacenters/2210/virtualappliances/1085/virtualmachines/1126/action/reset \ 
	 -H 'Accept:application/vnd.abiquo.acceptedrequest+json; version=4.2' \ 
	 -u user:password --verbose

Success status code: 202

Request payload:

--none--

Response payload:

{
  "message": "You can keep track of the progress in the link", 
  "links": [
    {
      "href": "http://localhost:9009/api/cloud/virtualdatacenters/2210/virtualappliances/1085/virtualmachines/1126/tasks/1fd663d5-1e66-4443-b94c-f78d13c9e62f", 
      "rel": "status"
    }
  ]
}

Delete an entity

To delete an entity, simply perform a DELETE request to the API link. But remember that there may be restrictions on what you can delete. For example, you cannot delete a virtual datacenter that contains virtual appliances. If we delete the VM using the following query, it will be removed from the platform (and if it exists on the hypervisor, it will be destroyed). The NIC we added will be detached and released back into the virtual datacenter.

curl -X DELETE https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/26/virtualappliances/37/virtualmachines/198 \
     -H 'Accept: text/json,application/json;' \ 
	 -u user:password