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 Снапшот не найден
Ошибки выполнения асинхронного задания
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 }