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

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

{  

  "private_address":{  

  },

  "name":"My Test Server",

  "hostname":"cs12600.vscale.io",

  "public_address":{  

 

  },

  "keys":[  

     {  

        "id":92,

        "name":"mykey"

     }

  ],

  "made_from":"ubuntu_14.04_64_002_master",

  "created":"27.08.2015 14:28:51",

  "ctid":12600,

  "status":"defined",

  "active":false,

  "locked":true,

  "deleted":null,

  "rplan":"medium",

  "location":"spb0"

}

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

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

Просмотреть информацию о статусе всех текущих операций можно, выполнив GET-запрос на адрес https://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).

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

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

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

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

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

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

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

Пример 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