This tutorial continues on from Get Started with the Abiquo 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.
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.
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.
We will use this type of NIC link in the next step.
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.
You could perform a curl request from the command line, for example.
In our response body, there are 3 IP addresses: the gateway and two IP addresses we created specifically for this exercise.
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.
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".
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.
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.
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.
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.
Before you begin this section, deploy a VM through the user interface.
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.
Hard power off
The API will return a link where you can monitor the progress of this operation.
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.
To reset a VM using the API, use a POST request to the reset action link.
Success status code: 202
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.