Quick Start guide to Gigas Api¶

Summary¶

In this tutorial we will go through all the required steps to create a machine and confirm it’s creation.

Requirements¶

In order to follow this tutorial you’ll need some application that allows to make requests to a web server through different HTTP methods (GET, POST, PUT, DELETE). Some examples are:

Curl.
An app called Postman.
A Firefox extension called RestClient.
Any other rest client or programming library.

Conventions through the tutorial¶

We will be using curl through this document as it is commonly installed in many linux distributions, but everything should be easily translated to any other tool you decide to use.

Your username and password for the API will be the email and password you used for registering in Gigas. We will be refering to those as:

username: email
password: password
url: https://api.gigas.com

For brevity we will write the token as:

token: apitoken

Authentication¶

Prior to any action on the Api, there needs to be an authentication. By doing this we will get a token which we must copy somewhere safe and provide it in further calls.

Each token has a life span of 30 minutes.

In order to ask for a token, we will issue the following command:

curl -i -X POST https://api.gigas.com/token -d '{ "login": "youremail@xxxxxx.com", "password": "yourpassword" }' -H "Content-Type: application/json"

This will get us a response like:

{"token": "11b03ec85b271fa5174cc88f571e5ace406d2a93f2719396",
"expires": "1369241120"}

The only field that matters for this tutorial is token, as expiration is given purely as a convenience information. Copy the value of the token field as we will use it in the following sections.

Note

Remember that in the following sections of the tutorial, whenever the example writes apitoken you’ll have to substitute it with the token field (in the example it was: 11b03ec85b271fa5174cc88f571e5ace406d2a93f2719396 withouth the quotes)

Note

The temporal token has an expiration timer of 30 minutes, if it expires just ask for a new one with the previous command.

Creation of a virtual machine¶

As an example of a POST request with queue, we will be creating a virtual machine.

Checking out the documentation for creating a virtual machine we can see the following information:

Method: POST
Url: /account/<account_id>/virtual_machine
Success Code: Success return Code: 202
Returned Data: Virtual machine resource
Has Token: Yes

From that section we know it is a POST method request, its url and that it will return a token meaning that it will take a small amount of time until the virtual machine is fully built.

Checking also the required parameters we will create a minimal virtual machine with the following command:

curl -i -X POST https://api.gigas.com/account/ACCOUNT_ID/virtual_machine -d '{ "memory": "128", "cpus": "1", "label": "pruebaApi", "primary_disk_size": "5", "swap_disk_size": "1", "hostname": "pruebaApi", "location_id": 2, "template_id": "1789310154" }' -H "Authorization: apitoken" -H "Content-Type: application/json"

All the parameters used in the call are well documented but we will focus on the last one: template_id. In order to get a valid template id, we can refer to the list of available templates to search for one that suits our needs. For that we will issue another call to list templates which looks like:

Method: GET
Url: /account/<account_id>/templates
Success Code: 200
Returned Data: Template resource list
Has Token: Yes

Again we gather it is a GET method, its url and that it does not return a queue token but a template resource list from which we can find a suitable template for our example virtual machine.

The command (filtered to show only Debian results) could be like:

curl -i -X GET https://api.gigas.com/account/ACCOUNT_ID/templates?label=Debian -H 'Authorization: apitoken' -H 'Content-Type: application/json'

Which will produce the output:

[
    {
        "available": 1,
        "updated_at": "2017-11-29T11:08:15",
        "template_size": 408420,
        "clone_id": "913aa36d-2235-4cf9-b35f-2df7a988a69b",
        "allowed_swap": 1,
        "operating_system_arch": "x64",
        "location_id": null,
        "id": "1789310154",
        "operating_system_distro": "ubuntu",
        "operating_system_edition": null,
        "label": "Debian 7 x64 (Linux)",
        "parent_template_id": "1789310151",
        "version": "1.0",
        "public": true,
        "status": "active",
        "operating_system_tail": null,
        "min_memory_size": null,
        "hypervisor_version": null,
        "user_id": null,
        "grub_version": null,
        "min_disk_size": 5,
        "operating_system": "linux",
        "allowed_hot_migrate": 1,
        "hypervisor_operating_system": null,
        "error": 0,
        "date_created": "2013-06-17T16:19:22",
        "account_id": 17893
    },
    {
        "available": 1,
        "updated_at": "2017-11-29T11:08:15",
        "template_size": 408420,
        "clone_id": "0dcc6690-8a8c-42b1-9146-009578af2037",
        "allowed_swap": 1,
        "operating_system_arch": "x64",
        "location_id": null,
        "id": "1789310155",
        "operating_system_distro": "ubuntu",
        "operating_system_edition": null,
        "label": "Debian 8 Plesk 12 x64 (Linux)",
        "parent_template_id": "1789310151",
        "version": "1.0",
        "public": true,
        "status": "active",
        "operating_system_tail": null,
        "min_memory_size": 512,
        "hypervisor_version": null,
        "user_id": null,
        "grub_version": null,
        "min_disk_size": 5,
        "operating_system": "linux",
        "allowed_hot_migrate": 1,
        "hypervisor_operating_system": null,
        "error": 0,
        "date_created": "2013-06-17T16:19:22",
        "account_id": 17893
    },
    {
        "available": 1,
        "updated_at": "2017-11-29T11:08:15",
        "template_size": 408420,
        "clone_id": "001a2422-fcc2-4751-bde4-9e8d5db38770",
        "allowed_swap": 1,
        "operating_system_arch": "x64",
        "location_id": null,
        "id": "1789310156",
        "operating_system_distro": "ubuntu",
        "operating_system_edition": null,
        "label": "Debian 8 x64 (Linux)",
        "parent_template_id": "1789310151",
        "version": "1.0",
        "public": true,
        "status": "active",
        "operating_system_tail": null,
        "min_memory_size": 512,
        "hypervisor_version": null,
        "user_id": null,
        "grub_version": null,
        "min_disk_size": 5,
        "operating_system": "linux",
        "allowed_hot_migrate": 1,
        "hypervisor_operating_system": null,
        "error": 0,
        "date_created": "2013-06-17T16:19:22",
        "account_id": 17893
    }
]

Now that we know what the template_id is, we can issue the previous command:

curl -i -X POST https://api.gigas.com/account/ACCOUNT_ID/virtual_machine -d '{ "memory": "128", "cpus": "1", "label": "pruebaApi", "primary_disk_size": "5", "swap_disk_size": "1", "hostname": "pruebaApi", "location_id": 2, "template_id": "1789310154" }' -H "Authorization: apitoken" -H "Content-Type: application/json"

Which will output something like:

{
    "updated_at": "2018-05-29T08:20:49",
    "vip": false,
    "suspended": 0,
    "label": "testapi",
    "location_id": "178931012",
    "id": "178931011513",
    "template_label": null,
    "is_deletion_machine": false,
    "hostname": "testapi",
    "custom": false,
    "note": null,
    "local_remote_access_port": null,
    "boot_type": "default",
    "memory": 256,
    "type": "standard",
    "virtualization_type": null,
    "status": "unbuilt",
    "initial_password": "rYXtg8cCdLQI",
    "console_lang": "en",
    "operating_system_distro": null,
    "hypervisor_id": "178931017",
    "booted_from": "hd",
    "cpus": 1,
    "strict_virtual_machine_id": null,
    "cdrom": 0,
    "user_id": "178931011324",
    "disk_type": "vd",
    "operating_system": null,
    "locked": 1,
    "created_at": "2018-05-29T08:20:49",
    "remote_access_password": null,
    "cpu_type": "amd",
    "error": 0,
    "identifier": "3geg9n6kbswbq4",
    "template_id": "1789310154",
    "cpu_shares": 1,
    "account_id": 17893,
    "queue_token": "7d9c9446-e2bd-4992-90e6-2c3930dfc757"
}

Most of the virtual machine parameters will already be there, although it isn’t built yet. In order to know the status of a task the identifier in the queue_token field comes to play. Also, remember the id of the virtual machine as it will be used to modify and delete it. In our example the virtual machine id is 317893101151 and we will use that number throughout the tutorial, but you’ll have to replace it with the one in your response.

Asking for queue status¶

Having copied the queue_token field identifier, we can query the status of a task issuing the following command:

curl -i -X GET https://api.gigas.com/account/ACCOUNT_ID/transaction/32072/status -H 'Authorization: apitoken' -H 'Content-Type: application/json'

Which will inform of the current status of the task. If we are quick enough, the virtual machine wont be built yet and it will output:

{"status": "pending"}

But finally it will end in:

{"status": "complete"}

Modifying a virtual machine¶

As the virtual machine is complete, we can modify it. But to make it quick we will only change it’s label. Refer to Edit virtual machine data section to see available parameters.

This is a PUT method that can return either a 200 or a 202, meaning that some operations are instant (200) and some others get a queue token and will take some time to complete (202). As said before, we will change only its label, which won’t make us wait:

curl -i -X PUT https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/178931011513 -d '{"label": "NewLabel"}' -H 'Authorization: apitoken' -H 'Content-Type: application/json'

And it will immediately return with the result:

{
    "updated_at": "2018-05-29T09:03:10",
    "vip": false,
    "suspended": 0,
    "label": "NewLabel",
    "location_id": "178931012",
    "id": "178931011513",
    "template_label": "Debian 7 x64 (Linux)",
    "is_deletion_machine": false,
    "hostname": "testapi",
    "custom": false,
    "note": null,
    "local_remote_access_port": 5906,
    "boot_type": "default",
    "memory": 256,
    "type": "standard",
    "virtualization_type": null,
    "status": "online",
    "initial_password": "rYXtg8cCdLQI",
    "console_lang": "en",
    "operating_system_distro": "ubuntu",
    "hypervisor_id": "178931017",
    "booted_from": "fd",
    "cpus": 1,
    "strict_virtual_machine_id": null,
    "cdrom": 1,
    "user_id": "178931011324",
    "disk_type": "vd",
    "operating_system": "linux",
    "locked": 0,
    "created_at": "2018-05-29T08:20:49",
    "remote_access_password": "462611d73ee1",
    "cpu_type": "amd",
    "error": 0,
    "identifier": "3geg9n6kbswbq4",
    "template_id": "1789310154",
    "cpu_shares": 1,
    "account_id": 17893
}

As mentioned before, if the call issues a 202 as its successful return code, this means it will take some time to complete the changes and a queue token will be given to know the status of the task.

Deletion of a virtual machine¶

Finally, as we don’t need this machine for anything else, we will delete it. If you check the documentation it’s noted as a DELETE method with a return of 202 as it will take some time to do a full and secure wipe of the disks as well as releasing some other resources attached to the virtual machine.

Note

Everytime we destroy a resource it will either return a 202 or a 204, meaning that in the response body there will only be a token or no content at all.

We can issue the command:

curl -i -X DELETE https://api.gigas.com/account/ACCOUNT_ID/virtual_machine/178931011513 -H 'Authorization: apitoken' -H 'Content-Type: application/json'

In this case is a 202:

{"queue_token": 32074}

Ask for help if you need it¶

At Gigas Hosting, we hope to have provided you with the all the information you need to use the Api to your best interests, but in case something is not clear enough or there is any inaccuracy, please contact our awesome support team so we can solve it as soon as possible.

Quick Start guide to Gigas Api¶

Summary¶

Requirements¶

Conventions through the tutorial¶

Authentication¶

Creation of a virtual machine¶

Asking for queue status¶

Modifying a virtual machine¶

Deletion of a virtual machine¶

Ask for help if you need it¶

Table of Contents

Previous topic

Next topic