Work with the Vscale API

In the previous article, we just casually mentioned that Vscale is equipped with a simple and convenient API, which significantly simplifies the interaction of developers with the infrastructure. Today we will talk about the features and functions of the API in more detail.

The Vscale API is located at api.vscale.io/v1 .
With it, you can perform the same actions as through the control panel:
')

• create and delete servers;
• change the server configuration to a more productive one and switch to another tariff plan;
• disable, enable and restart servers;
• receive information on payments and debits from the account;
• work with the ticket system (create new tickets, send comments, close tickets).

The interaction is carried out using standard HTTP requests. JSON format is used for data exchange.
If the request is processed successfully, the API will return the object model in JSON format. If an error occurs, you will receive its code and a brief description (it is contained in the Vscale-Error-Message header).

Token generation

To get started with the API, you must first go through the full registration procedure (including SMS confirmation) and replenish the balance. Tokens are used to identify users. To get a token, log in to the control panel and go to the settings page .
In the menu on the left side of the page, select "Token management".

Click on the "Create Token" button. The following window will open:



Enter a brief description of the token in the appropriate field. Pay attention to the checkbox "Token type". Tokens for working with API are divided into two types:

• full-featured - can be used with all types of queries to perform all possible operations;
• read-only tokens - can be used only in GET requests; the number of operations performed with them is limited (for example, you can view the list of servers or available configurations with such a token, but you can no longer create a new server).

After setting the desired settings, click on the “Generate Token” button. After that, a new token will be added to the list. It will need to be transmitted in all requests in the X-Token header.
You can generate as many tokens as you need to work. The validity of tokens is unlimited.

Create a new server

Recall the procedure for creating a new server described in the previous article: first you need to give the server a name, then select the configuration and the OS image, and finally, configure the access method. When creating a server through the API, all necessary server characteristics are transferred in the request body. Here is a list of required parameters:

• make_from is the OS image selected for installation on the server: debian_8.1_64_001_master, centos_7.1_64_001_master, ubuntu_14.04_64_002_master (for details on how to get a list of available images, read more here );
• rplan - server configuration name; from the previous article, you already know that we offer 5 available configurations. Here are their names (in ascending order): small, medium, large, huge, monster. How to get a list of configurations, you can read more in the documentation for the API .
• do_start: true - service parameter indicating that the server should be started immediately after installation;
• name - server name;
• keys - SSH-key identification number, which will be used for access to the server (for more details on managing SSH-keys, see here );
• password - password (if password access is required);
• locations is the data center where the server will be located (today this parameter can have only one value - spb).

Here is an example of a request to create a server:

$ curl -i -X POST 'https://api.vscale.io/v1/scalets' -d '{"make_from":"ubuntu_14.04_64_002_master","rplan":"medium","do_start":true,"name":"My First Server","keys":[92],"location":"spb0"}' -H 'X-Token:5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


If the request is processed correctly, then a response will be returned containing all the characteristics passed in the request, as well as a number of additional service parameters:

{"name": "Icy-Mysterious", "deleted": null, "rplan": "medium", "made_from": "ubuntu_14.04_64_002_master", "status": "defined", "hostname": "cs14174.vscale.io", "created": "27.08.2015 10:03:07", "ctid": 12600, "private_address": {}, "location": "spb0", "keys": [{"name": "key", "id": 92}], "public_address": {}, "active": false, "locked": true}


Status of current operations

Review the sample response in the previous section again and notice the status field. According to the logic of things, if the server was created successfully, the created status should be returned, but in the given example, the corresponding parameter has a different meaning, defined. By creating servers through a graphical interface, status changes can be observed in real time. In the API, this is not possible, and the status of objects does not change instantly.
You can view information about the status of all current operations by issuing a GET request to api.vscale.io/v1/tasks :

$ curl -i api.vscale.io/v1/tasks

[{"location": "spb0", "d_insert": "2015-08-28 12:37:48", "id": "3a447f17-3577-4c16-b26c-27bd52faa7c1", "done": false, "scalet": 12835, "error": false, "d_start": "2015-08-28 09:37:48", "method": "scalet_create", "d_end": null}


From the given example response, it is clear that the server creation operation ("method": "scalet_create") is in progress, that it is not yet completed ("done": false) and that no errors were detected during its execution ("error": false).

Server operations

Configuration upgrade

Using the API, you can always switch from the current configuration to a more productive one. Downward configuration is impossible.
When creating our test server, we chose the medium configuration. Change it to large:

$ curl 'https://api.vscale.io/v1/scalets/12600/upgrade'-X POST -d '{"rplan":"large"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


If the request is successful, a response will be returned with information about the server:

{"private_address": {}, "name": "New-Eyelid", "hostname": "cs12600.vscale.io", "public_address": {"address": "95.213.195.101", "netmask": "255.255.255.0", "gateway": "95.213.195.1"}, "keys": [{"id": 72, "name": "key"}], "made_from": "ubuntu_14.04_64_002_master", "created": "27.08.2015 14:28:51", "ctid": 12600, "status": "updated", "active": true, "locked": false, "deleted": null, "rplan": "medium", "location": "spb0"}


Server reboot

The server is restarted using a PATCH request. Example:

$ curl -i -X PATCH api.vscale.io/v1/scalets/12600/restart -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


The response will list the parameters of the restarted server.

Shut down and turn on the server

Shutting down and turning on the server is also performed using PATCH requests:

 # server shutdown

$ curl -i -X PATCH api.vsale.io/v1/scalets/12600/stop -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36


 # turn on the server 

$ curl -i -X PATCH api.vsale.io/v1/scalets/12600/start -d '{"id": "12600"}' -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


Server removal

To delete a server, you must perform a DELETE request:

$ curl -i -X DELETE api.vscale.io/v1/scalets/12600 -H 'X-Token: 5c22a088f3b37c933e7480399f1e09258d6977bcd1eb2401de29e8001c9bedc36'


The response will return the parameters of the remote server.

Conclusion

In this article, we explained how you can manage servers using the Vscale API. This is only a small part of the API capabilities: read more about all the functions in the official documentation . We will appreciate any feedback.
The version of API brought to your attention is the first. If it, in your opinion, lacks any functions, let us know. We will certainly take into account the most interesting proposals and suggestions in the work on the next version.