2Safe API
h1. Модель вызова функций в API (JSON)
Передаём параметры любым способом (POST, GET)
https://api.2safe.com/?cmd=команда
https://apiqa.2safe.com/?cmd=команда QA сервер
Ответ от API сервера в формате JSON. При возникновении ошибки выдаётся сообщение с кодом ошибки:
{ "error_code": "006", // код ошибки, в случае ошибки "error_msg": "Command not found" // сообщение, в случае ошибки }
Код ошибки и сообщение с ошибкой возвращается во всех командах, ТОЛЬКО при возникновении ошибки.
h2. Проверка доступности e-mail
<cmd: chk_mail
<email:
{ "response" : { "success" : "true", // true в случае успеха "available": "true" // true - доступен, false - занят } }
h2. Проверка доступности логина
<cmd: chk_login
<login:
{ "response" : { "success" : "true", // true в случае успеха "available": "true" // true - доступен, false - занят } }
h2. Получение капчи
<cmd: get_captcha
Ответ будет получен как при обычном GET запросе (изображение image/png) с заголовком "Set-Cookie: captcha2safe=1000", где 1000 - id капчи. Код действителен в течении 10 минут.
h2. Регистрация пользователя
<cmd: add_login
<login:
<password:
<email:
<captcha: // защитный код, полученный предварительным запросом get_captcha, если код не верен, то необходимо заново получить капчу.
<id: // id капчи, который находится в заголовке ответа на запрос get_captcha или в cookie c именем captcha2safe
{ "response" : { "success" : "true", // true в случае успеха "root" : "17050000001", // id корневой папки "id" : "1033000001" // id пользователя } }
h2. Авторизация пользователя
<cmd:auth // команда
<login:
<password:
<format: // по умолчанию JSON - параметр может использоваться во всех запросах к API
{ "response" : { "success" : "true", "id" : "1033000001", // id пользователя "token" : "e726e3df64a55ceff84754e3157053cc" // token для дальнейших действий } }
h2. Удаление пользователя
<cmd: remove_login
<login:
<password:
{ "response" : { "success" : "true", "user" : { "id" : "1034000001", "login" : "test22" } } }
h2. Удаление сессии (logout)
<cmd: logout
<token:
{ "response" : { "success" : "true" // true в случае успеха } }
h2. Просмотр квоты
<cmd: get_disk_quota
<token:
{ "response" : { "quotas" : { "used_bytes" : 121404289, // использовано "total_bytes" : 2048000000 // всего }, "success" : "true" } }
h2. Получение карточки юзера
<cmd: get_personal_data
<token:
{ "response" : { "success" : "true", "props" : { "key2" : "val2", "key1" : "value1", "keyN" : "valueN" }, "personal" : { "email" : "test-17786c8b1@mail.ru", "lang" : "en", "last_name" : "Testovich", "first_name" : "Test", "avatar" : "21212000001" } } }
h2. Изменение карточки юзера
<cmd: set_personal_data
<token:
<personal: // данные в формате JSON в виде хеша ключ-значение {"first_name":"value1","last_name":"value2","lang":"ru|en"}
<props: // произвольные данные в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
{ "response" : { "success" : "true", // true в случае успеха } }
h2. Смена пароля
<cmd: change_password
<login:
<password:
<new_password:
{ "response" : { "success" : "true", // true в случае успеха } }
h2. Получение файла
<cmd: get_file
<id: // id файла
<token:
<size:
<offset:
Ответ будет получен как при обычном GET запросе, без учёта формата запроса (JSON,XML и т.д.)
h2. Заливка файла
Загрузка файлов производится методом POST (multipart/form-data)
<cmd: put_file
<dir_id: // id папки назначения
<file: // файл
<token:
Опциональные параметры:
<overwrite // автоматически заменять файл с таким же именем, если параметр не задан, то при наличии такого же файла без признака версионности - возвращается ошибка
<versioned: // если файл существует, то создаётся новая версия файла
<props: // произвольные свойства в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
<ctime // дата создания (в формате timestamp)
<mtime // дата модификации (в формате timestamp)
{ "response" : { "success" : "true", "file" : { "mtime" : 1337004875, "chksum" : "d1e4164d404141efe1b0d5f4ef30e9f4", "name" : "Brazil - Lagoa.jpg", "oid" : "17330000001", "type" : "image/jpeg", "id" : "17329000001", "size" : 150197 } } }
h2. Копирование файлов
<cmd: copy_file
<id: // id файла
<dir_id: // id папки куда, копируется файл
<token:
<overwrite: // если файл существует, то он перезаписывается
<versioned: // если файл существует, то создаётся новая версия файла
<file_name: // новое имя файла (для копирования с переименовыванием)
{ "response" : { "success" : "true" // true в случае успеха } }
h2. Перемещение файлов
<cmd: move_file
<id:
// id файла
<dir_id: // id папки куда, перемещаем файл
<token:
<overwrite: // если файл существует, то он перезаписывается
<versioned: // если файл существует, то создаётся новая версия файла
<file_name: // новое имя файла (для перемещения с переименовыванием)
{ "response" : { "success" : "true", // true в случае успеха "id" : "17329000001" // новый id файла } }
h2. Удаление файлов
<cmd: remove_file
<id: // id файла
<token:
{ "response" : { "success" : "true" // true в случае успеха } }
h2. Создание директорий
<cmd: make_dir
<dir_id: // id корневой паки
<dir_name: // имя папки
<token:
Опциональные параметры: <props: // произвольные свойства в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"} <ctime // дата создания (в формате timestamp)
<mtime // дата модификации (в формате timestamp)
{ "response" : { "success" : "true", // true в случае успеха "dir_id" : "17750000001" // id новой директории } }
h2. Копирование директорий
<cmd: copy_dir
<id: // id src каталога
<dir_id: // id корневого dst каталога
<token:
<overwrite: // автоматически перезаписывать файлы и папки
<versioned: // если файл существует, то создаётся новая версия файла
<dir_name: // новое имя папки (для копирования с переименовыванием)
{ "response" : { "success" : "true" // true в случае успеха } }
h2. Перемещение директорий
<cmd: move_dir
<id: // id src каталога
<dir_id: // id корневого dst каталога
<token: <overwrite: // автоматически перезаписывать файлы
<versioned: // если файл существует, то создаётся новая версия файла
<dir_name: // новое имя папки (для перемещения с переименовыванием)
{ "response" : { "success" : "true" // true в случае успеха } }
h2. Удаление директорий
<cmd: remove_dir
<dir_id: // id каталога
<token:
<recursive // рекурсивное удаление
{ "response" : { "success" : "true" // true в случае успеха } }
h2. Просмотр директорий
Получение списка файлов, каталогов, шар
<cmd: list_dir
<dir_id: // id каталога, при пустом значении выдаёт список файлов и папок корневого каталога
<token:
{ "response" : { "success" : "true", "list_dirs" : [ { "ctime" : 1337003006, "props" : { "key4" : "value4", "key3" : "value3" }, "mtime" : 1337003006, "name" : "sub_new_dir", "id" : "17071000001", "owner" : "test123", "shared" : 1, "versioned": 1, // если каталог для версионных файлов, то 1 "c_type" : "httpd/unix-directory" }, { "ctime" : 1337003026, "mtime" : 1337003026, "name" : "new_dir4", "id" : "17106000001", "versioned": 0, "c_type" : "httpd/unix-directory" } ], "root" : { "tree" : "/new_dir2/", // дерево где находимся в данный момент "name" : "new_dir2", "id" : "17068000001", // id просматриваемого каталога, если входной id не задан, то id корня "parent_id" : "17058000001" }, "list_files" : [ { "ctime" : 1337003021, "current_version" : "17090000001", "mtime" : 1337003021, "name" : "null_bytes_file.txt", "id" : "17089000001", "owner" : "test123", "chksum" : "f436859c01b419731a6c7bc9c81c795f", "c_type" : "plain/text", "version_count" => 1, // Количество версий файла "shared" : 1, 'public_link' => 'http://devel.2safe.com:8082/17089000001/null_bytes_file.txt', "size" : 0 }, { "ctime" : 1337004875, "current_version" : "17330000001", "mtime" : 1337004875, "name" : "Brazil - Lagoa.jpg", "id" : "17329000001", "c_type" : "image/jpeg", 'version_count' => 2, // Количество версий файла "size" : 150197 } ] } }
h2. Очистка корзины
<cmd: purge_trash
<token:
<container // необязательный параметр
{ "response" : { "success" : "true" // true в случае успеха } }
h2. Получение свойств объекта
а так же получение id объекта, если на входе url или получение url, если на входе id
<cmd: get_props
<url: // путь к файлу или каталогу ИЛИ
<id: // id объекта
<token:
<container // имя контейнера (по умолчанию default), если используем url
{ "response" : { "success" : "true", "object" : { "owner" : "test123", "ctime" : 1337004875, "tree" : "/new_dir2/Brazil - Lagoa.jpg", "dir_id" : "17068000001", "creator" : "test123", "mtime" : 1337004875, "name" : "Brazil - Lagoa.jpg", "size" : 150197, "parent_id" : "17068000001", "props" : { "key4" : "value4", "key3" : "value3" }, "current_version" : "17330000001", "chksum" : "d1e4164d404141efe1b0d5f4ef30e9f4", "id" : "17329000001", "c_type" : "image/jpeg", "shared" : 1, "versioned": 1, // свойство каталога (если каталог для версионных файлов, то 1) "version_count" => 1, // Количество версий файла "public_link" => 'http://devel.2safe.com:8082/17329000001/Brazil - Lagoa.jpg', "perms" : "read", } } }
h2. Установка свойств объекта
<cmd: set_props
<id: // id объекта
<token:
<props: // произвольные свойства в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
{ "response" : { "success" : "true", // true в случае успеха } }
h2. Получение родительского дерева каталогов
<cmd: get_tree
<token:
<dir_id
{ "response" : { "success" : "true", "tree" : [ { "owner" : "test123", "level" : "0", "name" : "Shared", "id" : "17053000001", "parent_id" : "17050000001" }, { "owner" : "test123", "level" : "1", "name" : ".root", "id" : "17050000001" } ] } }
h2. Блокировка объекта
<cmd: lock_object
<token:
<id: // id объекта
<exclusive: // св-ва блокировки
<inheritable:
<timeout:
<userdata: // пользовательские данные
{ "response" : { "success" : "true", "lock_token" : "a9151295e505db40c3e147da16354f22" } }
h2. Разблокировка объекта
<cmd: unlock_object
<token:
<lock_token:
{ "response" : { "success" : "true" // true в случае успеха } }
h2. Получение списка всех блокировок
<cmd: list_object_locks
<token:
<id: // id объекта
{ "response" : { "success" : "true", "list_locks" : [ { "userdata" : "", "token" : "6c27f95fa4b946e7a6015d742b0998d2", // lock_token "expires" : "2147483647", "exclusive" : "0", "inheritable" : "0" } ] } }
h2. Обновление таймаута блокировки
<cmd: refresh_lock_timeout
<token:
<lock_token:
<timeout:
{ "response" : { "success" : "true", "userdata" : "", "exclusive" : "0", "inheritable" : "0" } }
h2. Расшаривание объекта
<cmd: share_object
<token:
<id: // id объекта
<login: // логин друга, для кого расшариваем
<write: // для расшаривания на запись параметр = 1
<expires: // срок расшаривания в формате timestamp
{ "response" : { "success" : "true" } }
h2. Отменить расшаривание объекта
<cmd: unshare_object
<token:
<id: // id объекта
<login: // логин друга, для кого было расшарен объект
{ "response" : { "success" : "true" } }
h2. Отменить все шары объекта
<cmd: unshare_all
<token:
<id: // id объекта
{ "response" : { "success" : "true" } }
h2. Список шар объекта
<cmd: list_shares
<token:
<id: // id объекта
{ "response" : { "shares" : [ { "login" : "test-a7f", "write" : 1, "expires" : 1340797745, // либо 0, если нет ограничений по сроку } ], "success" : "true" } }
h2. Публичность объекта
<cmd: public_object
<token:
<id: // id объекта
<expires: // срок публичности в формате timestamp
{ "response" : { "link" : "http://cdn808.2safe.com/43190000001/litmus.jpg", "success" : "true" } }
h2. Отменить публичность объекта
<cmd: unpublic_object
<token:
<id: // id объекта
{ "response" : { "success" : "true" } }
h2. Просмотр действий пользователя
<cmd: get_events
<token:
<after: // timestamp в формате 1340713368454494 (наносекунды) (без этого параметра выводятся все события)
<last: // вывести только последнее событие
{ "response" : { "success" : "true", "events" : [ { "timestamp" : 1340713368454494, "name" : "new_dir", "id" : "12749000001", "event" : "dir_created", "parent_id" : "12741000001" }, { "timestamp" : 1340713368576917, "name" : "new_dir2", "id" : "12751000001", "event" : "dir_created", "parent_id" : "12741000001" }, { "event" : "file_moved", "timestamp" : 1340715512685817, "old_parent_id" : "14307000001", "new_id" : "14308000001", "new_parent_id" : "14228000001", "old_id" : "14308000001", "old_name" : "file_30_bytes", "new_name" : "file_30_bytes" } ] } }
h2. Получение списка версий файла
<cmd: list_versions
<token:
<id: // id файла
{ "response" : { "success" : "true", "versions" : [ { "ctime" : 1340797746, "owner" : "test123", "mtime" : 1340797754, "name" : "file_name", "size" : 0, "chksum" : "d41d8cd98f00b204e9800998ecf8427e", "id" : "18408000001", "c_type" : "plain/text" }, { "ctime" : 1340797745, "owner" : "test123", "mtime" : 1340797750, "name" : "file_name", "size" : 60, "chksum" : "f436859c01b419731a6c7bc9c81c795f", "id" : "18395000001", "c_type" : "plain/text" } ] } }
h2. Получение текущей версии файла
<cmd: get_current_version
<token:
<id: // id файла
{ "response" : { "success" : "true", "current_version" : "18518000001" } }
h2. Установка текущей версии файла
<cmd: set_current_version
<token:
<id: // id файла
<v_id: // id версии
{ "response" : { "success" : "true" } }
h2. Удаление версии файла
<cmd: remove_version
<token:
<id: // id версии
{ "response" : { "success" : "true" } }