API

Описание

Управление боксами можно осуществлять через ПУ или через наше API.
Для вызова метода API нужно отправить POST-запрос с параметрами метода по протоколу HTTP.

Запрос следует отправлять по адресу:
https://api.from.sh/sprintbox/{object}/{action}, где:
{object} - сущность, например: box, backup;
{action} - действие над сущностью, например: add, delete.

В ответ будет получен JSON-объект в кодировке UTF-8 с полями data, error.
В случае успешного выполнения запроса поле data содержит результат выполенного запроса и код состояния сервера 200 ОК.

При возникновении ошибки поле error содержит код (error.code) и описание ошибки (error.description). Код состояния сервера в таком случае 400 Bad Request.

Для аутентификации обязательна отправка заголовков: AUTH-LOGIN: {login}
AUTH-KEY: {key}
Логин и ключ можно получить в личном кабинете.

Типы запросов

Синхронные - получение результата в ответ на запрос
Асинхронные - получение id задания для проверки статуса выполнения методом status/show

Коды ошибок

Код Сообщение Описание
Ошибки аутентификации
40001 Empty key Не передан ключ доступа
40002 Access login Не передан логин
40003 Access denies Ошибка аутентификации, переданы неверные данные
Общие ошибки
40011 Unknown method Неизвестный метод
40012 Empty required params Отсутствуют обязательные поля (: перечень полей)
Ошибки выполнения метода
41001 Unknown service Неизвестная услуга бокса
41002 Statement less than service fee Недостаточно средств на счету
41003 Account boxes over limit Превышен лимит боксов для одного аккаунта
41004 Box can not delete today Нельзя удалить бокс в день его создания
41005 Nothing to change Переданные параметры совпадают с конфигурацией бокса
41006 Box not found Бокс не найден
41007 Backup not found Бекап не найден
41008 Backup is not supported Неподдерживаемый формат бекапа для создания бокса
41009 Can not change service Некорректная услуга для модификации бокса
41010 Backups over limit Создано максимальное количество бекапов для бокса
41015 Snapshots over limit Создано максимальное количество снапшотов для бокса
41016 Snapshot not found Снапшот не найден
41024 Error while adding scheduled tasks Ошибка при создании автоматического бекапа по расписанию
41025 Error while removing scheduled tasks Ошибка при удалении автоматического бекапа по расписанию
41101 Scheduled backup start time incorrect Некорректное время начала создания автоматических бекапов
41102 Scheduled backup end end incorrect Некорректное время окончания создания автоматических бекапов
41103 Scheduled backup end time less than start time Время окончания создания автоматических бекапов меньше чем время начала
41104 Scheduled backup modify empty arguments Не переданы аргументы для изменения автоматических бекапов по расписанию
41105 Delete backups to add scheduled Лимит доступных бекапов бокса достигнут. Необходимо удалить бекапы, чтобы создать автоматические бекапы по расписанию
41106 Encode box scheduled backup info failed Ошибка сохранения параметров бекапов по расписанию
41107 Box scheduled backup service not found for customer К боксу не подключен сервис автоматических бекапов
41108 Additional backups service not found Не найдет подходящий сервис дполонительных бекапов для данного бокса
41109 Can't disable additional backups. Backups limit of $limit achieved Невозомжно отключить сервис бекапов по расписанию. Текущее количество бекапов превышает допустимый начальный лимит
41110 There is no backup services to delete Невозомжно отключить сервис допольнительных бекапов. Сервис либо не подключен, либо не существует
Ошибки выполнения асинхронного задания
35001 Critical error Критическая ошибка выполнения задания
35002 Validation error Ошибка валидации переданных параметров
35003 Does not exists Сущность не найдена
35004 Already exists Сущность уже существует
35005 Process timeout Задача завершена по таймауту
35006 Unknown error Неизвестная ошибка
35007 Json decode failed Ошибка декодирования json-объекта
35008 Error system user Ошибка прав доступа пользователя
35009 Unavailable service API-cервис временно недоступен

Примеры

Рассмотрим пример создания нового бокса из базового дистрибутива.

1. Получение списка доступных дистрибутивов

Запрос отправляется методом distributives/list без параметров $ curl https://api.from.sh/sprintbox/distributives/list -H "AUTH-LOGIN: login" -H "AUTH-KEY: randomkey" Результат выполнения запроса { "data": { "debian7": { "name": "debian7", "description": "Debian 7.9 \"Wheezy\"", "x64": true, "x86": true }, "debian8": { "name": "debian8", "description": "Debian 8.5 \"Jessie\"", "x64": true, "x86": true }, "ubuntu1404": { "name": "ubuntu1404", "description": "Ubuntu 14.04.3 LTS \"Trusty Tahr\"", "x64": true, "x86": true }, "ubuntu1604": { "name": "ubuntu1604", "description": "Ubuntu 16.04.1 LTS \"Xenial Xerus\"", "x64": true, "x86": true } }, "error": null }

2. Получение списка доступных услуг для боксов

Запрос отправляется методом services/list без параметров $ curl https://api.from.sh/sprintbox/services/list -H "AUTH-LOGIN: login" -H "AUTH-KEY: randomkey" Результат выполнения запроса { "data": [ { "name": "box32_2gb_1core", "description": "Бокс 32 ГБ, ОЗУ 2 ГБ, 1 ядро", "fee": 400 }, { "name": "box32_2gb_2cores", "description": "Бокс 32 ГБ, ОЗУ 2 ГБ, 2 ядра", "fee": 599 }, { "name": "box48_4gb_1core", "description": "Бокс 48 ГБ, ОЗУ 4 ГБ, 1 ядро", "fee": 999 }, { "name": "box48_4gb_2cores", "description": "Бокс 48 ГБ, ОЗУ 4 ГБ, 2 ядра", "fee": 1199 } ], "error": null }

3. Создание нового бокса

Отправляется запрос box/add со следующими параметрами:
service - название сервиса;
distributive - название базового дистрибутива;
arch - архитектура. $ curl --data "service=&arch=x64&distributive=debian8" https://api.from.sh/sprintbox/box/add -H "AUTH-LOGIN: login" -H "AUTH-KEY: randomkey" Результат выполнения запроса { "data": { "id": "a7890c4b-7a75-480f-b7fd-014272728ac0" }, "error": null } data.id - идентификатор асинхронного задания по созданию бокса.

4. Проверка статуса выполнения асинхронного задания

Статус обычно проверяется в цикле, пока не будет получен один из результирующий статусов: finished, error $ curl --data "id=a7890c4b-7a75-480f-b7fd-014272728ac0" https://api.from.sh/sprintbox/status/show -H "AUTH-LOGIN: login" -H "AUTH-KEY: randomkey" Результат успешно выполненного задания. Бокс создан успешно. { "data": { "id": "a7890c4b-7a75-480f-b7fd-014272728ac0", "status": "finished" }, "error": null } Результат задания с ошибкой { "data": { "id": "a7890c4b-7a75-480f-b7fd-014272728ac0", "status": "error" }, "error": { "code": 35003, "message": "Task 'a7890c4b-7a75-480f-b7fd-014272728a' does not exist" } } Со списком ошибок можно ознакомиться на странице коды ошибок.

5. Получение списка боксов аккаунта

Запрос отправляется методом boxes/list без параметров $ curl https://api.from.sh/sprintbox/boxes/list -H "AUTH-LOGIN: login" -H "AUTH-KEY: key" Результат выполнения запроса { "data": { "box-4869": { "name": "box-4869", "description": "debian8-32gb-2gb-1core", "distributive": "debian8", "arch": "x64", "cpu_count": 1, "memory": 2048, "hdd_quota": 32768, "hdd_used": 1517, "state_id": 1, "state_description": "running", "ipv4": [ "185.185.68.117" ], "ipv6": [ "2a0a:2b40::4:30" ], "vnc_ip": "141.8.196.171", "vnc_port": "5926", "vnc_password": "wjcmfpff", "use_vlan": true, "services": [ { "name": "box32_2gb_1core", "count": 1 } ], "backups": [] }, "box-5467": { "name": "box-5467", "description": "debian8-32768gb-2048gb-1core", "distributive": "debian8", "arch": "x64", "cpu_count": 1, "memory": 2048, "hdd_quota": 32768, "hdd_used": 1504, "state_id": 1, "state_description": "running", "ipv4": [ "185.185.69.90" ], "ipv6": [], "vnc_ip": "141.8.196.171", "vnc_port": "5919", "vnc_password": "niveviye", "use_vlan": false, "services": [ { "name": "box32_2gb_1core", "count": 1 } ], "backups": [] } }, "error": null }