Версия 17:26, 1 октября 2012

Модель вызова функций в 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"	// сообщение, в случае ошибки
}

Код ошибки и сообщение с ошибкой возвращается во всех командах, ТОЛЬКО при возникновении ошибки.

Пользовательские функции

Проверка доступности e-mail

<cmd: chk_mail <email:

{
	"response" : {
		"success" : "true",			// true в случае успеха
		"available": "true"			// true - доступен, false - занят
		}
}

Проверка доступности логина

<cmd: chk_login <login:

{
	"response" : {
		"success" : "true",			// true в случае успеха
		"available": "true"			// true - доступен, false - занят
		}
}

Получение капчи

<cmd: get_captcha

Ответ будет получен как при обычном GET запросе (изображение image/png) с заголовком "Set-Cookie: captcha2safe=1000", где 1000 - id капчи. Код действителен в течении 10 минут.

Регистрация пользователя

<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 пользователя
	}
}

Авторизация пользователя

<cmd: auth // команда <login: <password: Опциональные параметры: <format: // по умолчанию JSON - параметр может использоваться во всех запросах к API <captcha_id: // После трёх и более неправильных попыток авторизации необходимо получить новую капчу get_captcha <captcha: // и передать эти два параметра

{
	"response" : {
		"success" : "true",
		"id" : "1033000001",							// id пользователя
		"token" : "e726e3df64a55ceff84754e3157053cc"	// token для дальнейших действий
	}
}

Срок действия token - 24 часа. После каждого обращения к API - срок действия токена обновляется и становится равным 24 часам. По истечении token'а необходимо заново авторизоваться.

Удаление пользователя

<cmd: remove_login <login: <password:

{
	"response" : {
		"success" : "true",
		"user" : {
			"id" : "1034000001",
			"login" : "test22"
			}
	}
}

Удаление сессии (logout)

<cmd: logout <token:

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Просмотр квоты

<cmd: get_disk_quota <token:

{
	"response" : {
		"quotas" : {
			"used_bytes" : 121404289,	// использовано
			"total_bytes" : 2048000000	// всего
			},
		"success" : "true"
	}
}

Получение карточки юзера

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

Изменение карточки юзера

<cmd: set_personal_data <token: <personal: // данные в формате JSON в виде хеша ключ-значение {"first_name":"value1","last_name":"value2","lang":"ru|en"} Опциональный параметр: <props: // произвольные данные в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"} <password // обязательное поле только при смене email

{
	"response" : {
		"success" : "true",			// true в случае успеха          
	}
}

При изменении email необходимо передавать текущий пароль в параметр password.

Смена пароля

<cmd: change_password <login: <password: <new_password:

{
	"response" : {
		"success" : "true",			// true в случае успеха          
	}
}

Активация промо кода

<cmd: activate_promo_code <token: <\code:

{
	"response" : {
		"quotas" : {
			"used_bytes" : 121404289,	// использовано
			"total_bytes" : 5368709120,	// всего
			"difference": 2048000000	// сколько добавлено за счёт активации кода
			},
		"success" : "true"
	}
}

После трёх неудачных попыток введения промо кода - таймаут 5 минут.

== Функции по работе с файловой системой --

Получение файла

<cmd: get_file <id: // id файла <token: Опциональные параметры: <size: <offset:

Ответ будет получен как при обычном GET запросе, без учёта формата запроса (JSON,XML и т.д.)

Заливка файла

Загрузка файлов производится методом POST (multipart/form-data)

<cmd: put_file <dir_id: // id папки назначения <file: // файл <token: Опциональные параметры: <overwrite // автоматически заменять файл с таким же именем, если параметр не задан, то при наличии такого же файла без признака версионности - возвращается ошибка <versioned: // если файл существует, то создаётся новая версия файла, независимо от флага overwrite <props: // произвольные свойства в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"} <ctime // дата создания (в формате timestamp) <mtime // дата модификации (в формате timestamp) <name // имя для файла в системе

{
	"response" : {
		"success" : "true",
		"file" : {
			"mtime" : 1337004875,
			"chksum" : "d1e4164d404141efe1b0d5f4ef30e9f4",
			"name" : "Brazil - Lagoa.jpg",
			"version_id" : "17330000001",
			"type" : "image/jpeg",
			"id" : "17329000001",
			"size" : 150197
			}
	}
}

Копирование файлов

<cmd: copy_file <id: // id файла <dir_id: // id папки куда, копируется файл <token: Опциональные параметры: <overwrite: // если файл существует, то он перезаписывается <versioned: // если файл существует, то создаётся новая версия файла <file_name: // новое имя файла (для копирования с переименовыванием)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Перемещение файлов

<cmd: move_file <id: // id файла <dir_id: // id папки куда, перемещаем файл <token: Опциональные параметры: <overwrite: // если файл существует, то он перезаписывается <versioned: // если файл существует, то создаётся новая версия файла <file_name: // новое имя файла (для перемещения с переименовыванием либо переименовыванием)

{
	"response" : {
		"success" : "true",		// true в случае успеха
		"id" : "17329000001"		// новый id файла
		}
}

id файла изменяется только при перемещении, кроме перемещения в корзину. Переименовывание файла происходит так же со сменой id.

Удаление файлов

<cmd: remove_file <id: // id файла <token: Опциональный параметр: <remove_now // удаление минуя корзину (Аналог Shift+Del)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

При первом удалении файл удаляется в корзину (папка Trash), при повторном выполнении ф-ии - файл удаляется навсегда. При попадании в корзину файлу присваивается флаг old_path с полным путём, откуда он был удалён.

Создание директорий

<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 новой директории
	}
}

Копирование директорий

<cmd: copy_dir <id: // id src каталога <dir_id: // id корневого dst каталога <token: Опциональные параметры: <overwrite: // автоматически перезаписывать файлы и папки <versioned: // если файл существует, то создаётся новая версия файла <dir_name: // новое имя папки (для копирования с переименовыванием)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Перемещение директорий

<cmd: move_dir <id: // id src каталога <dir_id: // id корневого dst каталога <token: Опциональные параметры: <overwrite: // автоматически перезаписывать файлы <versioned: // если файл существует, то создаётся новая версия файла <dir_name: // новое имя папки (для перемещения с переименовыванием либо переименовыванием)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Удаление директорий

<cmd: remove_dir <dir_id: // id каталога <token: Опциональные параметры: <recursive // рекурсивное удаление <remove_now // удаление минуя корзину (Аналог Shift+Del)

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

При первом удалении папка удаляется в корзину (в папку Trash), при повторном выполнении ф-ии - папка удаляется навсегда. При попадании в корзину папке присваивается флаг old_path с полным путём, откуда она была удалёна.

Просмотр директорий

Получение списка файлов, каталогов, шар

<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"
				},
				{
				"owner":"test123",
				"ctime":1343139621,
				"special_dir":"shared",		// Для спец. дирректорий поле принимает значение trash|shared
				"creator":"test456",
				"mtime":1343394246,
				"name":"Shared",
				"shared":0,
				"versioned":0,
				"props":{},
				"id":"4561000001",
				"c_type":"httpd/unix-directory"
            			},
				{
				"owner":"test123",
				"creator":"test456",			
				"ctime" : 1337003026,
				"mtime" : 1337003026,
				"name" : "new_dir4",
				"id" : "17106000001",
				"versioned": 0,
				"c_type" : "httpd/unix-directory",
				"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
				"is_shared" : 1,					// см. логику флагов
				"shared_parents" : ["56531000001","40562000001"],	// см. логику флагов
				"perms" : "read",					// см. логику флагов 
				"versioned_parent" : "17330000001",	// см. логику флагов
				"old_path" : "/new_dir2/new_dir4/"	// При удалении в корзину папка приобретает данный флаг, который содержит полный путь до удаления
				}
			],
		"root" : {
			"tree" : "/new_dir2/",			// дерево где находимся в данный момент
			"name" : "new_dir2",
			"id" : "17068000001",			// id просматриваемого каталога, если входной id не задан, то id корня
			"parent_id" : "17058000001",
			"versioned" : 0,					// если данный каталог, либо каталог уровнем ниже версионный. Если 1 то все файлы и папки в этом каталоге по умолчанию версионные.
			"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
			"is_shared" : 1,					// см. логику флагов
			"shared_parents" : ["40562000001"],	// см. логику флагов
			"perms" : "read",					// см. логику флагов 
			"versioned_parent" : "17330000001"	// см. логику флагов
			},
		"list_files" : [
				{
				"ctime" : 1337003021,
				"current_version" : "17090000001",
				"mtime" : 1337003021,
				"name" : "null_bytes_file.txt",
				"id" : "17089000001",
				"owner" : "test123",
				"chksum" : "f436859c01b419731a6c7bc9c81c795f",
				"c_type" : "plain/text",
				"versioned" : 1,	// версионный файл
				"version_count" : 2,	// Количество версий файла
				"shared" : 1,
				"public_link" : "http://cdn.2safe.com/17089000001/null_bytes_file.txt",
				"public_expires": 1348697574,	// Срок истечения публичности
				"size" : 0,
				"total_size" : 30	// Итоговый размер всех версий
				},
				{
				"owner":"test123",
				"creator":"test456",
				"ctime" : 1337004875,
				"current_version" : "17330000001",
				"mtime" : 1337004875,
				"name" : "Brazil - Lagoa.jpg",
				"id" : "17329000001",
				"c_type" : "image/jpeg",
				"versioned" : 0,
				"version_count" : 2,			// Количество версий файла
				"size" : 150197,
				"total_size": 150197,
				"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
				"is_shared" : 1,					// см. логику флагов
				"shared_parents" : ["56531000001","40562000001"],	// см. логику флагов
				"perms" : "read",					// см. логику флагов 
				"versioned_parent" : "17330000001",	// см. логику флагов
				"old_path" : "/new_dir2/Brazil - Lagoa.jpg"	// При удалении в корзину файл приобретает данный флаг, который содержит полный путь до удаления
				}
			]
	}
}

Логика флагов

Для функций get_props и list_dir:

+У владельца:+

shared = 1 - только у того объекта, для которого была выполнена команда share_object, соответственно для этого объекта можно выполнить команду list_shares shared_parents = массив id_родителей - у тех объектов, которые являются потомками, где первый элемент массива означает текущую ближайшую шару, а остальные в порядке удаления от потомка, т.е. данный флаг имеют падпапки расшаренного объекта, у данных объектов shared = 0 versioned_parent = id_родителя - у тех объектов, которые являются потомками, т.е. падпапки версионной папки, у них так-же versioned = 1

+У того, кому расшарили (в папке Shared):+

shared = 0 - у всех объектов, перерасшаривание и публикация так же запрещена/ perms = read|write - права на объекты (файлы и папки) is_shared = 1 - у всех объектов в папке Shared.

Получение свойств объекта

а так же получение id объекта, если на входе url или получение url, если на входе id

<cmd: get_props <url: // путь к файлу или каталогу ИЛИ <id: // id объекта <token: Опциональный параметр: <container // имя контейнера (по умолчанию default), если используем url

Для файлов:

{
    "response":{
        "success":"true",
        "object":{
		"dir_id":"16137033537",
		"creator":"user_test",
		"tree":"/Shared/sql_sync.files",
		"size":1510178,		// Размер
		"shared":1,
		"current_version":"16125033025",
		"version_count":3,		// Количество версий файла
		"chksum":"cc16eb82a3314053d94cb390df9cb149",
		"id":"16140033537",
		"owner":"user_test",
		"ctime":1343203344,
		"mtime":1343215109,
		"name":"sql_sync.files",
		"total_size":4530534,	// Итоговый размер (сумма размеров всех версий)
		"versioned":0,
		"props":{
			"flags":"136",
			"mode":"33204"
		},
		"c_type":"application/octet-stream",
		"public_link" : "http://cdn.2safe.com/16140033537/sql_sync.files",
		"public_expires": 1348697574,			// Срок истечения публичности
		"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
		"is_shared" : 1,					// см. логику флагов
		"shared_parents" : ["56531000001","40562000001"],	// см. логику флагов
		"perms" : "read",					// см. логику флагов 
		"versioned_parent" : "17330000001",	// см. логику флагов
		"old_path" : "/Shared/sql_sync.files"	// При удалении в корзину файл приобретает данный флаг, который содержит полный путь до удаления
        }
    }
}

Для папок:

{
	"response" : {
		"success" : "true",
		"object" : {
			"owner" : "test123",
			"ctime" : 1337004875,
			"tree" : "/new_dir2/",
			"creator" : "test456",
			"mtime" : 1337004875,
			"name" : "new_dir2",
			"parent_id" : "17068000001",
			"props" : {
				"key4" : "value4",
				"key3" : "value3"
				},
			"id" : "17329000001",
			"c_type" : "httpd/unix-directory",
			"shared" : 1,
			"versioned": 1,
			"special_dir" : "",			// Для спец. дирректорий поле принимает значение trash|shared в остальных случаях отсутствует               
			"is_trash" : 1,					// Если объект находится в папке Trash, в остальных случаях флаг отсутствует
			"is_shared" : 1,					// см. логику флагов
			"shared_parents" : ["56531000001","40562000001"],	// см. логику флагов
			"perms" : "read",					// см. логику флагов 
			"versioned_parent" : "17330000001",	// см. логику флагов
			"old_path" : "/new_dir2/"	// При удалении в корзину папка приобретает данный флаг, который содержит полный путь до удаления
			}
	}
}

Установка свойств объекта

<cmd: set_props <id: // id объекта <token: <props: // произвольные свойства в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}

{
	"response" : {
		"success" : "true",			// true в случае успеха          
	}
}

Получение родительского дерева каталогов

<cmd: get_tree_parent <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"
				}
			]
	}
}

Очистка корзины

<cmd: purge_trash <token: Опциональный параметр: <container // необязательный параметр

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Просмотр действий пользователя

<cmd: get_events <token: Опциональные параметры: <after: // timestamp в формате 1340713368454494 (наносекунды) (без этого параметра выводятся первые 300 событий) <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"
                      }
		]
	}
}

Функция get_events без опциональных параметров выводит первые 300 событий, для получения следующий событий, необходимо передавать параметр after, в котором указывать timestamp последнего элемента массива из предудущего запроса.

Функции по работе с блокировками

Блокировка объекта

<cmd: lock_object <token: <id: // id объекта Опциональные параметры: <exclusive: // св-ва блокировки <timeout: <userdata: // пользовательские данные

{
	"response" : {
		"success" : "true",
		"lock_token" : "a9151295e505db40c3e147da16354f22"
	}
}

Разблокировка объекта

<cmd: unlock_object <token: <lock_token:

{
	"response" : {
		"success" : "true"			// true в случае успеха
		}
}

Получение списка всех блокировок

<cmd: list_object_locks <token: <id: // id объекта

{
	"response" : {
		"success" : "true",
		"list_locks" : [
				{
				"userdata" : "",
				"token" : "6c27f95fa4b946e7a6015d742b0998d2",		// lock_token
				"expires" : 2147483647,
				"exclusive" : 0
				}
			]
	}
}

Обновление таймаута блокировки

<cmd: refresh_lock_timeout <token: <lock_token: <timeout:

{
	"response" : {
		"success" : "true",
		"userdata" : "",
		"exclusive" : 0
	}
}

Функции расшаривания и публикации объектов

Расшаривание объекта

<cmd: share_object <token: <id: // id объекта <login: // логин друга, для кого расшариваем Опциональные параметры: <write: // для расшаривания на запись параметр = 1 <expires: // срок расшаривания в формате timestamp

{
	"response" : {
		"success" : "true"
	}
}

Права на write означают возможность производить любые операции над объектом, кроме ф-ий расшаривания и версионности. Перерасшаривание и установка/снятие версионности при флаге write ЗАПРЕЩЕНА!

Отменить расшаривание объекта

<cmd: unshare_object <token: <id: // id объекта <login: // логин друга, для кого было расшарен объект

{
	"response" : {
		"success" : "true"
	}
}

Команда unshare_object применима только к тем объетам, к которым применялась команда share_object

Отменить все шары объекта

<cmd: unshare_all <token: <id: // id объекта

{
	"response" : {
		"success" : "true"
	}
}

Команда unshare_all применима только к тем объетам, к которым применялась команда share_object

Список шар объекта

<cmd: list_shares <token: <id: // id объекта

{
	"response" : {
		"shares" : [
				{
				"login" : "test-a7f",
				"write" : 1,
				"inherited_from" : "12741000001",		// id родительской шары, либо отсутствует, если шара не наследуемая
				"expires" : 1340797745,     // либо 0, если нет ограничений по сроку
				}
			],
		"success" : "true"
	}
}

Флаг inherited_from указывает id родительской шары, если помимо шары для данного объекта, существуют вложенные шары верхнего уровня и их действие так же распространяется на этот объект. Например: /dir1-shared_for_login1_rw/dir2-shared_for_login2-r/ При выполнении команды list_shares для dir2 ответ: {login=login2,write=0},{login=login1,write=1,inherited_from=12741000001} При выполнении команды list_shares для dir1 ответ: {login=login1,write=1}

Команда list_shares применима только к тем объетам, к которым применялась команда share_object

Публичность объекта

<cmd: public_object <token: <id: // id объекта Опциональный параметр: <expires: // срок публичности в формате timestamp

{
	"response" : {
		"link" : "http://cdn808.2safe.com/43190000001/litmus.jpg",
		"success" : "true"
	}
}

Команда public_object применима только к файлам.

Отменить публичность объекта

<cmd: unpublic_object <token: <id: // id объекта

{
	"response" : {
		"success" : "true"
	}
}

Команда unpublic_object применима только к файлам, для которых была выполнена команда public_object

Функции по работе с версионностью

Получение списка версий файла

<cmd: list_versions <token: <id: // id файла

{
    "response":{
        "versions":[
            {
                "owner":"user_test",
                "ctime":1343203344,
                "creator":"user_test",
                "mtime":1343204013,
                "name":"sql_sync.files",
                "size":1510178,
                "chksum":"cc16eb82a3314053d94cb390df9cb149",
                "id":"16008033025",
                "c_type":"application/octet-stream"
	},
	{
                "owner":"user_test",
                "ctime":1343203344,
                "creator":"user_test",
                "mtime":1343203344,
                "name":"sql_sync.files",
                "size":1510178,
                "chksum":"cc16eb82a3314053d94cb390df9cb149",
                "id":"16141033537",
                "c_type":"application/octet-stream"
            }
        ],
        "success":"true",
	"current":"16141033537",	// Текущая версия
	"file_id":"79397000001"		// id файла
    }
}

Получение текущей версии файла

<cmd: get_current_version <token: <id: // id файла

{
	"response" : {
               "success" : "true",
               "current_version" : "18518000001"
        }
}

Установка текущей версии файла

<cmd: set_current_version <token: <id: // id файла <v_id: // id версии

{
	"response" : {
		"success" : "true"
	}
}

Удаление версии файла

<cmd: remove_version <token: <id: // id версии

{
	"response" : {
		"success" : "true"
	}
}

Установка флага версионности для объекта

Если флагом помечается каталог, то все файлы в этом и во вложенных каталогах будут версионными

<cmd: set_versioned <token: <id: // id файла или каталога

{
	"response" : {
		"success" : "true"
	}
}

Снятие флага версионности для объекта

Если флаг снимается с каталога, то все файлы в этом и во вложенных каталогах больше не будут версионными, за исключением случая, если на вложенный файл не проставлялся этот флаг

<cmd: unset_versioned <token: <id: // id файла или каталога

{
	"response" : {
		"success" : "true"
	}
}

Команда unset_versioned применима только к тем объектам, для которых была выполнена команда set_versioned