2Safe API — различия между версиями

Версия 09:26, 1 августа 2012

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

2Safe API — различия между версиями

Версия 09:26, 1 августа 2012

Навигация

Персональные инструменты

Пространства имён

Варианты

Просмотры

Ещё

Поиск

Навигация

Инструменты

@@ Строка 20: / Строка 20: @@
 <cmd: chk_mail
 <email:
@@ Строка 34: / Строка 35: @@
 <cmd: chk_login
 <login:
@@ Строка 55: / Строка 57: @@
 <cmd: add_login
 <login:
 <password:
 <email:
 <captcha:  // защитный код, полученный предварительным запросом get_captcha, если код не верен, то необходимо заново получить капчу.
 <id:  // id капчи, который находится в заголовке ответа на запрос get_captcha или в cookie c именем captcha2safe
@@ Строка 74: / Строка 81: @@
 <cmd:auth   // команда
 <login:
 <password:
 <format:	// по умолчанию JSON - параметр может использоваться во всех запросах к API
@@ Строка 92: / Строка 102: @@
 <cmd: remove_login
 <login:
 <password:
@@ Строка 110: / Строка 122: @@
 <cmd: logout
 <token:
@@ Строка 123: / Строка 136: @@
 <cmd: get_disk_quota
 <token:
@@ Строка 140: / Строка 154: @@
 <cmd: get_personal_data
 <token:
@@ Строка 165: / Строка 180: @@
 <cmd: set_personal_data
 <token:
 <personal:   // данные в формате JSON в виде хеша ключ-значение {"first_name":"value1","last_name":"value2","lang":"ru|en"}
 <props:       // произвольные данные в формате JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
 <pre>
 {
 	"response" : {
@@ Строка 180: / Строка 199: @@
 <cmd: change_password
 <login:
 <password:
 <new_password:
@@ Строка 195: / Строка 217: @@
 <cmd: get_file
 <id:         	// id файла
 <token:
 <size:
 <offset:
@@ Строка 207: / Строка 233: @@
 <cmd: put_file
 <dir_id:         // id папки назначения
 <file:       // файл
 <token:
 Опциональные параметры:
 <overwrite	// автоматически заменять файл с таким же именем, если параметр не задан, то при наличии такого же файла без признака версионности - возвращается ошибка
 <versioned:		// если файл существует, то создаётся новая версия файла
 <props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
 <ctime             // дата создания (в формате timestamp)
 <mtime            // дата модификации (в формате timestamp)
@@ Строка 237: / Строка 272: @@
 <cmd: copy_file
 <id:                 //  id файла
 <dir_id:      // id папки куда, копируется файл
 <token:
 <overwrite:		// если файл существует, то он перезаписывается
 <versioned:		// если файл существует, то создаётся новая версия файла
 <file_name:    // новое имя файла (для копирования с переименовыванием)
@@ Строка 255: / Строка 296: @@
 <cmd: move_file
-<id:                 	//  id файла
+<id:
+                 	//  id файла
 <dir_id:      		// id папки куда, перемещаем файл
 <token:
 <overwrite:		// если файл существует, то он перезаписывается
 <versioned:		// если файл существует, то создаётся новая версия файла
 <file_name:    // новое имя файла (для перемещения с переименовыванием)
@@ Строка 274: / Строка 321: @@
 <cmd: remove_file
 <id:                 //  id файла
 <token:
@@ Строка 288: / Строка 337: @@
 <cmd: make_dir
 <dir_id:              	// id корневой паки
 <dir_name:   		// имя папки
 <token:
 Опциональные параметры:
-<props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
+<props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение
+{"key1":"value1","key2":"value2","keyN":"valueN"}
 <ctime             // дата создания (в формате timestamp)
 <mtime            // дата модификации (в формате timestamp)
@@ Строка 308: / Строка 363: @@
 <cmd: copy_dir
 <id:                 	//  id src каталога
 <dir_id:      		// id корневого dst каталога
 <token:
 <overwrite:		// автоматически перезаписывать файлы и папки
 <versioned:		// если файл существует, то создаётся новая версия файла
 <dir_name:    		// новое имя папки (для копирования с переименовыванием)
@@ Строка 326: / Строка 387: @@
 <cmd: move_dir
 <id:                 	//  id src каталога
 <dir_id:      		// id корневого dst каталога
 <token:
 <overwrite:		// автоматически перезаписывать файлы
 <versioned:		// если файл существует, то создаётся новая версия файла
 <dir_name:    		// новое имя папки (для перемещения с переименовыванием)
@@ Строка 344: / Строка 410: @@
 <cmd: remove_dir
 <dir_id:                 // id каталога
 <token:
 <recursive            // рекурсивное удаление
@@ Строка 361: / Строка 430: @@
 <cmd: list_dir
 <dir_id:                 // id каталога, при пустом значении выдаёт список файлов и папок корневого каталога
 <token:
@@ Строка 431: / Строка 502: @@
 <cmd: purge_trash
 <token:
 <container        // необязательный параметр
@@ Строка 447: / Строка 520: @@
 <cmd: get_props
 <url:		       	// путь к файлу или каталогу ИЛИ
 <id:                 	// id объекта
 <token:
 <container     		// имя контейнера (по умолчанию default), если используем url
@@ Строка 487: / Строка 564: @@
 <cmd: set_props
 <id:                 // id объекта
 <token:
 <props:            // произвольные свойства в формате  JSON в виде хеша ключ-значение {"key1":"value1","key2":"value2","keyN":"valueN"}
@@ Строка 502: / Строка 582: @@
 <cmd: get_tree
 <token:
 <dir_id
@@ Строка 531: / Строка 613: @@
 <cmd: lock_object
 <token:
 <id:			// id объекта
 <exclusive:		// св-ва блокировки
 <inheritable:
 <timeout:
 <userdata:		// пользовательские данные
@@ Строка 550: / Строка 638: @@
 <cmd: unlock_object
 <token:
 <lock_token:
@@ Строка 564: / Строка 654: @@
 <cmd: list_object_locks
 <token:
 <id:		// id объекта
@@ Строка 587: / Строка 679: @@
 <cmd: refresh_lock_timeout
 <token:
 <lock_token:
 <timeout:
@@ Строка 605: / Строка 700: @@
 <cmd: share_object
 <token:
 <id:		// id объекта
 <login:		// логин друга, для кого расшариваем
 <write:     // для расшаривания на запись параметр = 1
 <expires:   // срок расшаривания в формате timestamp
@@ Строка 622: / Строка 722: @@
 <cmd: unshare_object
 <token:
 <id:		// id объекта
 <login:		// логин друга, для кого было расшарен объект
@@ Строка 637: / Строка 740: @@
 <cmd: unshare_all
 <token:
 <id:		// id объекта
@@ Строка 651: / Строка 756: @@
 <cmd: list_shares
 <token:
 <id:		// id объекта
@@ Строка 672: / Строка 779: @@
 <cmd: public_object
 <token:
 <id:		// id объекта
 <expires:   // срок публичности в формате timestamp
@@ Строка 688: / Строка 798: @@
 <cmd: unpublic_object
 <token:
 <id:		// id объекта
@@ Строка 702: / Строка 814: @@
 <cmd:  get_events
 <token:
 <after:		// timestamp в формате 1340713368454494 (наносекунды) (без этого параметра выводятся все события)
 <last: // вывести только последнее событие
@@ Строка 743: / Строка 858: @@
 <cmd: list_versions
 <token:
 <id:		// id файла
@@ Строка 779: / Строка 896: @@
 <cmd: get_current_version
 <token:
 <id:		// id файла
@@ Строка 794: / Строка 913: @@
 <cmd: set_current_version
 <token:
 <id:		// id файла
 <v_id:      // id версии
@@ Строка 809: / Строка 931: @@
 <cmd: remove_version
 <token:
 <id:		// id версии