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