Работа с API Vscale

Vscale API расположен по адресу
api.vscale.io/v1
С его помощью можно выполнять те же действия, что и через панель управления:

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

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

developers.vscale.io/documentation/api/v1/

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

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

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

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

Создаём новый сервер
Вспомним порядок действий при создании нового сервера, описанный в предыдущей статье: сначала нужно дать серверу имя, затем выбрать конфигурацию и образ ОС и, наконец, настроить способ доступа. При создании сервера через 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' -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'

Если запрос обработан правильно, то будет возвращён ответ, содержащий все переданные в запросе характеристики, а также ряд дополнительных служебных параметров:

{"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. По логике вещей при успешном создании сервера должен быть возвращён статус created, но в приведённом примере соответствующий параметр имеет другое значение — defined. Создавая серверы через графический интерфейс, изменение статусов можно наблюдать в режиме реального времени. В API такой возможности нет, и статусы объектов изменяются не моментально.
Просмотреть информацию о статусе всех текущих операций можно, выполнив GET-запрос на адрес api.vscale.io/v1/tasks:

$ curl -i https://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}

Из приведённого примера ответа видно, что в текущий момент выполняется операция создания сервера («method»: «scalet_create»), что она ещё не завершена («done»: false) и что при её выполнении не обнаружено никаких ошибок («error»: false).

Апгрейд конфигурации
C помощью API всегда можно перейти с текущей конфигурации на более производительную. Изменение конфигурации в меньшую сторону (даунгрейд) невозможно.
При создании нашего тестового сервера мы выбрали конфигурацию medium. Изменим её на large:

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

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

{"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"}

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

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

В ответе будут перечислены параметры перезагруженного сервера.
Выключение и включение сервера
Выключение и включение сервера также осуществляются с помощью PATCH-запросов:
# выключение сервера

$ 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'

Удаление сервера
Чтобы удалить сервер, нужно выполнить DELETE-запрос:

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

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