Abiquo Documentation Cookies Policy

Our Documentation website uses cookies to improve your experience. Please visit our Cookie Policy page for more information about cookies and how we use them.


Abiquo 4.7

Skip to end of metadata
Go to start of metadata

Introduction

This tutorial continues on from Get Started with the Abiquo API!

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.

Links do more than just take you to related objects–they also define the configuration of a VM.

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. In this case, we will assume that the VM is not deployed.

  1. Open the browser console at the Network tab and record actions
  2. Edit the VM, go to Network → Private → select network → drag and drop an IP, and Save the VM
  3. 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.

Deployed VMs

If your VM is deployed, then it will already have a NIC. To work with a deployed VM, you may need to create another private network, because by default, you may not be able to add two NICs in the same private network. To change the configuration of a deployed VM, if the VM doesn't have network hot-reconfigure, then you will need to shut it down first.

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/2/privatenetworks/5/ips/16"
      }, 

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/2/privatenetworks/5/ips

You could perform a curl request from the command line, for example.

curl --verbose 'https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips' \
     -H 'Accept: application/vnd.abiquo.privateips+json; version=4.6' \
	 -u admin:xabiquo -k | 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...
user@user:~ $ curl --verbose 'https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips'      -H 'Accept: application/vnd.abiquo.privateips+json; version=4.6'  -u admin:xabiquo -k | jq .
* Connected to mjsabiquo.bcn.abiquo.com (10.60.13.180) port 443 (#0)
* Server auth using Basic with user 'admin'
> GET /api/cloud/virtualdatacenters/2/privatenetworks/5/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.6
> 
< HTTP/1.1 200 200
< Date: Wed, 19 Jun 2019 13:11:53 GMT
* Server Apache is not blacklisted
< Server: Apache
< Set-Cookie: ABQSESSIONID=5059746984440775455; Max-Age=1800; Expires=Wed, 19-Jun-2019 13:41:53 GMT; Path=/; Secure; HttpOnly
< X-Abiquo-Token: 2772ef503a95419ab7066ee6771751e6546ca200feb764385226ae9047a8f03e
< Content-Type: application/vnd.abiquo.privateips+json; version=4.6
< Transfer-Encoding: chunked
< 
* Connection #0 to host mjsabiquo.bcn.abiquo.com left intact
{
  "collection": [
    {
      "links": [
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5",
          "type": "application/vnd.abiquo.vlan+json",
          "rel": "privatenetwork",
          "title": "private_network_cloudland_01"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips/15",
          "type": "application/vnd.abiquo.privateip+json",
          "rel": "self",
          "title": "privateip"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "rel": "virtualdatacenter",
          "title": "bcdc_vdc_cloudland_01"
        }
      ],
      "id": 15,
      "ip": "192.168.201.1",
      "mac": "52:54:00:CD:25:F8",
      "name": "525400CD25F8_host",
      "networkName": "private_network_cloudland_01",
      "ipv6": false,
      "quarantine": false,
      "available": true
    },
    {
      "links": [
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5",
          "type": "application/vnd.abiquo.vlan+json",
          "rel": "privatenetwork",
          "title": "private_network_cloudland_01"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips/16",
          "type": "application/vnd.abiquo.privateip+json",
          "rel": "self",
          "title": "privateip"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "rel": "virtualdatacenter",
          "title": "bcdc_vdc_cloudland_01"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2",
          "type": "application/vnd.abiquo.virtualappliance+json",
          "rel": "virtualappliance",
          "title": "bcdc_vdc_cloudland_01_vapp_01"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/6",
          "type": "application/vnd.abiquo.virtualmachine+json",
          "rel": "virtualmachine",
          "title": "ABQ_331a9b47-5cf6-4166-bb02-021d5e8905df"
        }
      ],
      "available": true,
      "id": 16,
      "ip": "192.168.201.2",
      "mac": "52:54:00:5F:7D:68",
      "name": "5254005F7D68_host",
      "networkName": "private_network_cloudland_01",
      "ipv6": false,
      "usedBy": "ABQ_331a9b47-5cf6-4166-bb02-021d5e8905df",
      "quarantine": false
    },
    {
      "links": [
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5",
          "type": "application/vnd.abiquo.vlan+json",
          "rel": "privatenetwork",
          "title": "private_network_cloudland_01"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips/17",
          "type": "application/vnd.abiquo.privateip+json",
          "rel": "self",
          "title": "privateip"
        },
        {
          "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2",
          "type": "application/vnd.abiquo.virtualdatacenter+json",
          "rel": "virtualdatacenter",
          "title": "bcdc_vdc_cloudland_01"
        }
      ],
      "id": 17,
      "ip": "192.168.201.3",
      "mac": "52:54:00:DC:31:12",
      "name": "525400DC3112_host",
      "networkName": "private_network_cloudland_01",
      "ipv6": false,
      "quarantine": false,
      "available": true
    }
  ],
  "links": [
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/ips?limit=25&by=ip&asc=true",
      "rel": "first"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/privatenetworks/5/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 the 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 "17".

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/2/privatenetworks/5/ips/17",
          "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/2/privatenetworks/5/ips/17",
          "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/admin/enterprises/2",
      "type": "application/vnd.abiquo.enterprise+json",
      "rel": "enterprise",
      "title": "Cloudland"
    },
    {
      "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"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/publiccloudregions/1/enterprises/2/virtualmachines/8/action/sendmail",
      "type": "application/vnd.abiquo.mail+json",
      "rel": "sendmail",
      "title": "send mail"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/admin/enterprises/2/users/1",
      "type": "application/vnd.abiquo.user+json",
      "rel": "user",
      "title": "Cloud Administrator"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2",
      "type": "application/vnd.abiquo.virtualdatacenter+json",
      "rel": "virtualdatacenter",
      "title": "bcdc_vdc_cloudland_01"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2",
      "type": "application/vnd.abiquo.virtualappliance+json",
      "rel": "virtualappliance",
      "title": "bcdc_vdc_cloudland_01_vapp_01"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/metadata",
      "type": "application/vnd.abiquo.metadata+json",
      "rel": "metadata",
      "title": "metadata"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/network/configurations",
      "type": "application/vnd.abiquo.virtualmachinenetworkconfigurations+json",
      "rel": "configurations",
      "title": "vlan network configurations"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/network/nics",
      "type": "application/vnd.abiquo.nics+json",
      "rel": "nics",
      "title": "nics"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/storage/disks",
      "type": "application/vnd.abiquo.harddisks+json",
      "rel": "harddisks",
      "title": "disks"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/state",
      "type": "application/vnd.abiquo.virtualmachinestate+json",
      "rel": "state",
      "title": "NOT_ALLOCATED"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/action/undeploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "undeploy",
      "title": "virtual machine undeploy"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/action/deploy",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "deploy",
      "title": "virtual machine deploy"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/action/reset",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "reset",
      "title": "virtual machine reset"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/action/instance",
      "type": "application/vnd.abiquo.acceptedrequest+json",
      "rel": "instance",
      "title": "virtual machine snapshot"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/config/rdpaccess",
      "type": "application/vnd.abiquo.virtualmachineconsole+json",
      "rel": "rdpaccess",
      "title": "remote access"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/tasks",
      "type": "application/vnd.abiquo.tasks+json",
      "rel": "tasks",
      "title": "tasks"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/firewalls",
      "type": "application/vnd.abiquo.links+json",
      "rel": "firewalls",
      "title": "firewalls"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/loadbalancers",
      "type": "application/vnd.abiquo.loadbalancers+json",
      "rel": "loadbalancers",
      "title": "load balancers"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/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/2/virtualappliances/2/virtualmachines/8/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/2/virtualappliances/2/virtualmachines/8/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/2/virtualappliances/2/virtualmachines/8/action/move",
      "type": "application/vnd.abiquo.movevm+json",
      "rel": "move",
      "title": "move VM to another virtual datacenter"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/storage/volumes",
      "type": "application/vnd.abiquo.volumes+json",
      "rel": "volumes",
      "title": "volumes"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/disks/31",
      "type": "application/vnd.abiquo.harddisk+json",
      "rel": "disk0",
      "title": "9c83fcc3-e9cb-44bf-88d0-f8a98248fa69",
      "length": "64",
      "diskLabel": "Hard disk 1",
      "diskControllerType": "IDE"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/locations/1/datastoretiers/1",
      "type": "application/vnd.abiquo.datastoretier+json",
      "rel": "datastoretier0",
      "title": "Default Tier"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/action/protect",
      "type": "text/plain",
      "rel": "protect",
      "title": "protect"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/action/unprotect",
      "type": "text/plain",
      "rel": "unprotect",
      "title": "unprotect"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/metrics",
      "type": "application/vnd.abiquo.metricsmetadata+json",
      "rel": "metricsmetadata",
      "title": "metricsmetadata"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/enablemonitoring",
      "type": "",
      "rel": "enablemonitoring",
      "title": "enablemonitoring"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/metrics/collectd",
      "type": "application/json",
      "rel": "collectd",
      "title": "collectd"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/alarms",
      "type": "application/vnd.abiquo.alarms+json",
      "rel": "alarmssearch",
      "title": "alarmssearch"
    },
    {
      "href": "https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8/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/2/datacenterrepositories/1/virtualmachinetemplates/86",
      "type": "application/vnd.abiquo.virtualmachinetemplate+json",
      "rel": "virtualmachinetemplate",
      "title": "yvm2"
    },
    {
      "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/2/privatenetworks/5/ips/17",
      "type": "application/vnd.abiquo.privateip+json",
      "rel": "nic0",
      "title": "privateip"
    }
  ],
  "natrules": [],
  "generateGuestInitialPassword": false,
  "backuppolicies": [],
  "creationTimestamp": 1560939950000,
  "variables": {},
  "protected": false,
  "monitored": false,
  "ram": 48,
  "coresPerSocket": 1,
  "cpu": 1,
  "description": "A virtual machine",
  "label": "yVM_New",
  "name": "ABQ_06cfadf0-db57-48c5-8f4c-f9fe2ca76c46",
  "uuid": "06cfadf0-db57-48c5-8f4c-f9fe2ca76c46",
  "id": 8,
  "vdrpEnabled": true,
  "vdrpPort": 0,
  "idState": 1,
  "state": "NOT_ALLOCATED",
  "idType": 0,
  "type": "MANAGED",
  "highDisponibility": 0,
  "password": "VUFvbvoa"
}

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/2/virtualappliances/2/virtualmachines/8' \
	 -H 'Content-Type: application/vnd.abiquo.virtualmachine+json; version=4.6' \
     -H 'Accept: application/vnd.abiquo.acceptedrequest+json; version=4.6' \
	 -u admin:xabiquo \
 	 -d @VMnic.json -k 

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...
user@user:~/Documents/tutorials $ curl --verbose -X PUT 'https://mjsabiquo.bcn.abiquo.com:443/api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8'  -H 'Content-Type: application/vnd.abiquo.virtualmachine+json; version=4.6'      -H 'Accept: application/vnd.abiquo.acceptedrequest+json; version=4.6'  -u admin:xabiquo   -d @VMnic.json -k
* Connected to mjsabiquo.bcn.abiquo.com (10.60.13.180) port 443 (#0)
* Server auth using Basic with user 'admin'
> PUT /api/cloud/virtualdatacenters/2/virtualappliances/2/virtualmachines/8 HTTP/1.1
> Authorization: Basic YWRtaW46eGFiaXF1bw==
> User-Agent: curl/7.35.0
> Host: mjsabiquo.bcn.abiquo.com
> Content-Type: application/vnd.abiquo.virtualmachine+json; version=4.6
> Accept: application/vnd.abiquo.acceptedrequest+json; version=4.6
> Content-Length: 9805
> Expect: 100-continue
> 
< HTTP/1.1 100 Continue
< HTTP/1.1 204 204
< Date: Wed, 19 Jun 2019 13:30:55 GMT
< Server: Apache
< Set-Cookie: ABQSESSIONID=4974951206556392645; Max-Age=1800; Expires=Wed, 19-Jun-2019 14:00:55 GMT; Path=/; Secure; HttpOnly
< X-Abiquo-Token: 2772ef503a95419ab7066ee6771751e622f4fd0743fe006121a77f6b3213506b
< 


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:
  1. Perform a GET request to obtain the VM object and find the VM state link
  2. Create a virtualmachinestate object
  3. 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.

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

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

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

See https://wiki.abiquo.com/api/latest/VirtualMachinesResource.html#change-the-state-of-a-virtual-machine

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 through the API

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/2/virtualappliances/2/virtualmachines/8 \
     -H 'Accept: text/json,application/json;' \ 
	 -u user:password