Vscale API: краткое введение

Vscale API расположен по адресу https://api.vscale.io/v1.

С его помощью можно осуществлять те же действия, что и через панель управления: 

• создавать и удалять серверы;
• изменять конфигурацию сервера на более производительную ;
• отключать, включать и перезагружать серверы;
• получать информацию о платежах и списаниях со счёта;
• работать с тикет-системой (создавать новые тикеты, отправлять комментарии, закрывать тикеты).

Взаимодействие осуществляется при помощи стандартных HTTP-запросов. Для обмена данными используется формат JSON.

В случае успешной обработки запроса API вернёт модель объекта в формате JSON. При возникновении ошибки вы получите её код и краткое описание (оно содержится в заголовке Vscale-Error-Message).

Документация с подробным описанием функций API опубликована здесь.

Генерация токена

Чтобы начать работу с API, нужно сначала пройти полную процедуру регистрации (включая СМС-подтверждение) и пополнить баланс. Для идентификации пользователей используются токены.  Чтобы получить токен, авторизуйтесь в панели управления и перейдите на страницу настроек.

В меню в левой части страницы выберите пункт “Управление токенами”.

Нажмите на кнопку “Создать токен”. Откроется следующее окно:

Введите краткое описание токена в соответствующее поле. Обратите внимание на флажок “Тип токена”.  Для работы с API  используются токены двух типов:

• полнофункциональные — могут использоваться со всеми типами запросов для выполнения всех возможных операций;
• токены read-only — могут использоваться только в GET-запросах; количество выполняемых с ними операций ограничено (например, просмотреть список серверов или доступных конфигураций с таким токеном можно, а вот создать новый сервер —  уже нет).

Задав нужные настройки, нажмите на кнопку “Сгенерировать токен”.  После этого новый токен будет добавлен в список. Его нужно будет передавать во всех запросах в заголовке X-Token.

Вы можете сгенерировать столько токенов, сколько вам нужно для работы. Срок действия токенов неограничен.

Пример 1 создание нового сервера

Чтобы создать сервер через графический интерфейс, нужно выполнить следующие действия:  дать серверу имя, затем выбрать конфигурацию и образ ОС и, наконец, настроить способ доступа. При работе через API все необходимые характеристики сервера передаются в теле запроса. Обязательными для создания сервера параметрами являются следующие:

• make_from — образ ОС, выбранный для установки на сервере:  debian_8.1_64_001_master, centos_7.1_64_001_master, ubuntu_14.04_64_002_master (о том, как получить список доступных образов, подробнее читайте здесь):
• rplan — имя конфигурации сервера; из предыдущей статьи вы уже знаете, что мы предлагаем 5 доступных конфигураций. Вот их имена (в порядке возрастания): small, medium,large, huge, monster. Процедура получения списка конфигураций описана в документации к API.
• do_start: true — служебный параметр, указывающий, что сервер нужно запускать сразу же после установки;
• name —  имя сервера;
• keys — идентификационный номер SSH-ключа, по которому будет осуществляться доступ на сервер (об управлении SSH-ключами подробнее см. здесь);
• password — пароль (если требуется доступ по паролю)
• locations — дата-центр, в котором будет размещён сервер (на сегодняшний день этот параметр может иметь только одно значение — spb).

Запрос на создание сервера выглядит так:

$ curl -i -X POST 'https://api.vscale.io/v1/scalets' -H 'Content-Type: application/json;charset=UTF-8' -H 'X-Token: 5c21a467f3b37c331e7482599f1e0971c9bedc30258d6977bbd1db2401bb27e8' -d '{"make_from":"ubuntu_14.04_64_002_master","rplan":"medium","do_start":true,"name":"New-Test","keys":[16],"location":"spb0"}'

В случае успешного создания сервера будет возвращён ответ вида: 

HTTP/1.1 200 OK { 
"status": "defined", 
"deleted": null, 
"public_address": {}, 
"active": false, 
"location": "spb0", 
"locked": true, 
"hostname": "cs11533.vscale.io", 
"created": "20.08.2015 14:57:04", 
"keys": [ { "name": "somekeyname", "id": 16 } ], 
"private_address": {}, 
"made_from": "ubuntu_14.04_64_002_master", 
"name": "New-Test", 
"ctid": 11, 
"rplan": "medium" }

Статус текущих операций

Ещё раз просмотрите пример ответа в предыдущем разделе и обратите внимание на поле status.  По логике вещей при успешном создании сервера должен быть возвращён статус created, но в приведённом примере соответствующий параметр имеет другое значение — defined.  Создавая серверы через графический интерфейс, изменение статусов можно наблюдать в режиме реального времени. В API такой возможности нет, и статусы объектов изменяются не моментально.

Просмотреть информацию о статусе всех текущих операций можно, выполнив GET-запрос на адрес https://api.vscale.io/v1/tasks:

$ curl -i https://api.vscale.io/v1/tasks -H 'X-Token: 5c21a467f3b37c331e7482599f1e0971c9bedc30258d6977bbd1db2401bb27e8'

Пример 2:  апгрейд конфигурации

C помощью API всегда можно перейти с текущей конфигурации на более производительную. Переход на менее производительную конфигурацию (даунгрейд) невозможен.

При создании сервера в предыдущем примере мы выбрали конфигурацию medium.  Чтобы изменить её large, нужно отправить следующий запрос:

$ curl 'https://api.vscale.io/v1/scalets/270834/upgrade' -X POST -H 'X-Token: 5c21a467f3b37c331e7482599f1e0971c9bedc30258d6977bbd1db2401bb27e8' --data-binary '{"rplan":"monster"}' -H 'Content-Type: application/json;charset=UTF-8'

Как видно из приведённого примера, в теле запроса было передано имя новой конфигура ции в значении параметра rplan.

В случае успешного выполнения запроса будет возвращён ответ с информацией о сервере:

{"made_from": "ubuntu_14.04_64_002_master",
 "location": "spb0",
 "active": true,
 "created": "20.08.2015 14:57:04",
 "name": "New-Test", 
 "deleted": null, 
 "tags": [ ], 
 "keys": [], 
 "ctid": 11533,
 "rplan": "large",
 "hostname": "cs11533.vscale.io", 
 "locked": true, 
 "public_address": {"netmask": "255.255.255.0", "gateway": "212.92.98.1 ", "address": "212.92.98.194"}, 
 "status": "started",
 "private_address": {}}

Пример 3: перезагрузка, включение и выключение сервера

Операции включения, выключения и перезагрузки серверов осуществляются с помощью PATCH-запросов:

# перезагрузка сервера

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

# выключение сервера

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

#включение сервера

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

Пример 4: удаление сервера

Удаление к серверу осуществляется с помощью DELETE-запроса:

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

В ответе будут возвращены параметры удалённого сервера.

Заключение

В этой статье мы привели лишь самые простые примеры работы с API. Обо всех функциях и возможностях API можно прочитать в официальной документации. Текущая версия API — первая. Если в ней, по вашему мнению, не хватает каких-либо функций, сообщите нам об этом. Ваши предложения и пожелания мы учтём в работе над второй версией.

tglnkAPI