Описание ClodoAPI (версия 1.0)

Данный документ содержит описание ClodoAPI версии 1.0. Документ будет пополняться и расширяться по мере введения новой функциональности в API. По всем вопросам использования нашего api обращайтесь в службу технической поддержки Clodo.

• Авторизация
• Формат запроса
• Формат ответа
• Ограничения на количество запросов
• Работа с виртуальным сервером
  • Список виртуальных серверов (общая информация)
  • Список виртуальных серверов (подробная информация)
  • Получение информации по виртуальному серверу
  • Создание виртуального сервера
  • Изменение параметров виртуального сервера
  • Удаление виртуального сервера
  • Изменение типа виртуального сервера
  • Команды серверу
  • Статистика использования ресурсов
  • Лог работы виртуального сервера
• Управление резервными копиями виртуального сервера
  • Список резервных копий
  • Создать резервную копию
  • Удалить резервную копию
  • Восстановить из резервной копии
  • Статус восстановления
  • Установка календаря обновления резервной копии
  • Установка описания резервной копии
• Управление IP-адресами виртуального сервера
  • Список IP-адресов
  • Добавить IP-адрес
  • Удалить IP-адрес
  • Перемещение IP-адреса на другой сервер
  • Список подсетей
• Управление DNS
  • Получение списка зон
  • Добавление зоны
  • Удаление зоны
  • Просмотр зоны
  • Изменение зоны
  • Удаление записи в зоне
• Обращение в службу поддержки (Helpdesk)
  • Получение списка открытых запросов
  • Получение содержимого запроса
  • Добавление запроса в службу поддержки
  • Добавление сообщения в запрос
• Профиль пользователя
  • Получение профиля пользователя
  • Изменение профиля пользователя
• Cloud Storage
  • Получение списка хранилищ
  • Получение расширенной информации о хранилище
  • Изменение настроек хранилища
  • Создание хранилища
  • Удаление хранилища
• Дополнительные возможности
  • Получение статуса запроса
  • Запросы информации по биллингу
  • Доступные операционные системы (Images)

Авторизация

Свойства метода:

HTTP метод: GET
URI: /
Входные параметры (HTTP headers):

• X-Auth-User - логин пользователя
• X-Auth-Key - ключ пользователя (ключ можно заказать в панели управления ресурсами в разделе “Мой профиль”)

Выходные параметры (HTTP headers):

• X-Server-Management-Url - url доступа к функциям API
• X-Auth-Token - токен авторизации

Коды возврата:

• 204 - без ошибок
• 401 - ошибка авторизации

Пример запроса:

GET / HTTP/1.1  
Host: api.clodo.ru  
X-Auth-User: jdoe  
X-Auth-Key: a86850deb2742ec3cb41518e26aa2d89  

Пример ответа:

HTTP/1.1 204 No Content  
Date: Mon, 12 Nov 2007 15:32:21 GMT  
Server: Apache  
X-Server-Management-Url: https://api.clodo.ru/v1  
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb  
Content-Length: 0  
Content-Type: text/plain; charset=UTF-8  

Формат запроса

Обращение(кроме авторизации) должно производиться на адрес, полученный в поле “X-Server-Management-Url” при авторизации + URL команды.

Например:

X-Server-Management-Url: https://api.clodo.ru/v1
URL команды: /servers
Итоговый URL: https://api.clodo.ru/v1/servers

При каждом обращении к API (кроме авторизации) в заголовке HTTP-запроса должно присутствовать поле “X-Auth-Token” (значение этого поля получается при авторизации). Срок действия данного токена - 20 минут. По истечении данного времени необходимо заново произвести авторизацию и получить новый токен.

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

• Accept - указывает на формат, в котором вы хотите получить ответ (напр. “Accept: application/json” или “Accept: application/xml”);
• Content-type - формат, в котором вы передаете в запросе дополнительные параметры. Как и предыдущий может быть в двух вариантах - “Content-type: application/json; charset=UTF-8” или “Content-type: application/xml; charset=UTF-8”. Важен только в случае запроса, требующего дополнительных параметров.

Формат ответа

При ответе на запрос к API в зависимости от результатов обработки обращения выставляется соответствующий http-код. При успешном выполнения запроса будет установлен - 200 (если есть данные для возврата пользователю) или 204 (если данных нет). При ошибке будет установлен код 4xx (код варируется в зависимости от ошибки). Кроме того будет возвращено расширенное сообщение (в формате json или xml - в зависимости от поля “Accept” в запросе) со следующими параметрами:

• code - код ошибки
• message - наименование ошибки
• details - расширенное описание ошибки

Пример сообщения об ошибке:

<?xml version="1.0" encoding="UTF-8"?>
<Forbidden code="403">
  <message>Forbidden</message>
  <details>Доступ закрыт</details>
</Forbidden>

<?xml version="1.0" encoding="UTF-8"?>
<NotFound code="404">
  <message>Not Found</message>
  <details>VPS не найдена</details>
</NotFound>

{"NotFound":{"code":404,"message":"Not Found","details":"Модуль не найден"}}

Ограничения на количество запросов

Привязка лимитов осуществляется к пользователю, от имени которого делаются запросы. На данный момент выставлены следующие ограничения:

Здесь представлены значения по-умолчанию. Если Ваше приложение не укладывается в эти рамки, то по запросу в службу поддержки (с аргументацией необходимости изменения ограничений) могут быть внесены изменения для Вашего аккаунта.

Для получения текущих ограничений для Вашего аккаунта Вы можете использовать следующий запрос:

HTTP метод: GET
URI: /limits
Входные параметры: нет
Выходные параметры:

• verb - HTTP метод
• URI - шаблон URI
• regex - RegEx URI
• value - количество запросов в единицу времени
• remaining - осталось запросов до лимита
• unit - единица времени (MINUTE, HOUR, DAY)
• resetTime - сброс счетчика запросов (unix timestamp)

Коды возврата:

• 200 - без ошибок

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<limits>
  <rate>
    <limit verb="POST" URI="*" regex=".*" value="100" remaining="100" unit="MINUTE"
              resetTime="1302530220"/>
    <limit verb="POST" URI="*/servers" regex=" ^/servers" value="500" remaining="500" unit="DAY"
              resetTime="1302552000"/>
    <limit verb="PUT" URI="*" regex=".*" value="100" remaining="100" unit="MINUTE"
              resetTime="1302530220"/>
    <limit verb="DELETE" URI="*" regex=".*" value="100" remaining="100" unit="MINUTE"
              resetTime="1302530220"/>
    <limit verb="GET" URI="*" regex=".*" value="100" remaining="99" unit="MINUTE"
              resetTime="1302530220"/>
  </rate>
</limits>

{"limits":{"rate":[
{"verb":"POST","URI":"*","regex":".*","value":"100","remaining":100,"unit":"MINUTE",
        "resetTime":1302530580},
{"verb":"POST","URI":"*/servers","regex":"^/servers","value":"500","remaining":500,"unit":"DAY",
        "resetTime":1302552000},
{"verb":"PUT","URI":"*","regex":".*","value":"100","remaining":100,"unit":"MINUTE",
        "resetTime":1302530580},
{"verb":"DELETE","URI":"*","regex":".*","value":"100","remaining":100,"unit":"MINUTE",
        "resetTime":1302530580},
{"verb":"GET","URI":"*","regex":".*","value":"100","remaining":99,"unit":"MINUTE",
        "resetTime":1302530580}
]}}

Работа с виртуальным сервером

Раздел содержит описание набора методов для работы с виртуальными серверами на площадке Clodo.ru.

Список виртуальных серверов (общая информация)

Метод обеспечивающий получение списка виртуальных серверов на аккаунте и общей информации по виртуальным серверам.

Свойства метода:

HTTP метод: GET
URI: /servers

Входные параметры: нет

Выходные параметры:

• id - номер VPS
• name - название VPS(title)
• imageId - id операционной системы
• type - тип VPS
• status - статус VPS
• os_bits - битность ОС
• os_type - тип ОС
• addresses - ip-адреса
• public - публичные IP адреса
• private - приватные IP адреса

Коды возврата:

• 200 - без ошибок
• 404 - серверов не найдено

Пример ответа:

<?xml version="1.0" encoding="UTF-8"?>
<servers>
  <server>
    <id>60</id>
    <name>main</name>
    <imageId>561</imageId>
    <type>VirtualServer</type>
    <status>is_running</status>
    <os_type>debian</os_type>
    <os_bits>64</os_bits>
    <addresses>
      <public>
        <ip addr="188.127.237.202" primary_ip="1"/>
        <ip addr="188.127.237.203"/>
      </public>
    </addresses>
  </server>
  <server>
    <id>186</id>
    <name>scale</name>
    <imageId>531</imageId>
    <type>ScaleServer</type>
    <status>is_running</status>
    <os_type>centos</os_type>
    <os_bits>32</os_bits>
    <addresses>
      <public>
        <ip addr="188.127.245.119" primary_ip="1"/>
        <ip addr="188.127.245.120"/>
      </public>
    </addresses>
  </server>
</servers>

Список виртуальных серверов (подробная информация)

Метод обеспечивающий получение списка виртуальных серверов на а