NAV
← На сайт
HTTP

Введение

Запрос

HEAD /api HTTP/1.1
Host: download.ru

Ответ

HTTP/1.1 200 OK
Server: nginx
Date: Tue, 1 Apr 2015 00:00:01 GMT

Hello !!!

Это полный справочник по API сервиса download.ru - облачное хранилище файлов. Сайт поддерживает два типа API:

WebDAV API соответсвует WebDAV спецификации 2. Хост для запросов — https://webdav.download.ru

REST HTTP API спецификация описана ниже. Хост для запросов — https://download.ru

Это API официально используется web-интерфейсом сайта, поэтому весь его функционал также доступен для всех, без каких-либо ограничений.

Документация содержит примеры HTTP запросов в правой части экрана для ее более удобного восприятия.

Несколько простых требований, которые предъявляет API для его использования:

Авторизация

Авторизация работает по протоколу OAuth 2.0. Прежде всего вы должны создать свое приложение:

Пройдите по ссылке, чтобы прочитать полное руководство по протоколу OAuth 2.0.

Первое обращение к API (запрос настроек пользователя):

GET /account.json HTTP/1.1
Host: download.ru
Accept: application/json
Accept-Encoding: gzip

Рекомендуется первым запросом к API получить настройки пользователя, но это совершенно не обязательно.

Папки

Просмотр

Запрос корневой папки

GET /folders.json HTTP/1.1

Ответ

{
  "contents":[
    {
      "id":"xxxxxxxx",
      "name":"TEST",
      "shared":false,
      "parent_id":"xxxxxxxx",
      "user_id":"xxxxxxxx",
      "created_at":"2015-03-30T16:46:46.802+03:00",
      "updated_at":"2015-03-30T16:46:46.831+03:00",
      "is_dir":true,
      "secure_url":"/z/xxxxxxxx?e=xxxxxxxxxxxx&s=xxxxxxxxxxxx",
      "leaf":true,
      "whidden_folders":false,
      "whidden_files":false
    },
    {
      "id":"xxxxxxxx",
      "name":"photo.png",
      "description":null,
      "content_type":"image/png",
      "shared":false,
      "size":136335,
      "sha1":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "crc32":"xxxxxxxx",
      "parent_id":"xxxxxxxx",
      "sender_id":null,
      "user_id":"xxxxxxxx",
      "created_at":"2015-04-01T11:15:06.187+03:00",
      "updated_at":"2015-04-01T11:15:12.778+03:00",
      "is_dir":false,
      "icon":"icon-file-image",
      "preview":"image",
      "secure_url":"/g/xxxxxxxx/xxxxxxxx?f=photo.png&e=xxxxxxxx&s=xxxxxxxx",
      "last_interaction_at":"2015-04-01T11:15:06.187+03:00",
      "inline":true,
    }
  ],
  "object":{
    "id":"xxxxxxxx",
    "name":"Корневая папка",
    "shared":false,
    "parent_id":null,
    "user_id":"xxxxxxxx",
    "created_at":"2015-03-30T15:13:16.555+03:00",
    "updated_at":"2015-03-30T16:46:46.831+03:00",
    "is_dir":true,
    "secure_url":"/z/xxxxxxxx?e=xxxxxxxx&s=xxxxxxxx",
    "whidden_folders":false,
    "whidden_files":false,
    "ancestry":[
      {
        "id":"xxxxxxxx",
        "name":"Корневая папка",
        "name_short":"Корневая папка..."
      }
    ]
  }
}

Это интерфейс просмотра папок и их содержимого.

Параметры запроса

GET /folders.json - запрос корневой папки

GET /folders/xxxxxxxx.json - запрос любой другой папки

Параметры ответа

Ключ Тип Описание
object[id] String(8) Id папки
object[name] String Имя папки
object[shared] Boolean Общий доступ к папке.
object[parent_id] String(8) Id родительской папки. Для корневой папки он равен null.
object[user_id] String(8) Id владельца папки.
object[created_at] Timestamp Время создания папки
object[updated_at] Timestamp Время последнего изменения самой папки, но нее ее содержимого.
object[is_dir] Boolean Указывает на то, что объект именно папка, а не файл.
object[secure_url] String Временная ссылка на скачивание.
object[whidden_folders] Array[String(8)] Массив ids подпапок, которые не будут отображаться при подключении по WebDAV.
object[whidden_files] Array[String(8)] Массив ids файлов, которые не будут отображаться при подключении по WebDAV.
object[ancestry] Array[Object] Массив родительских папок. Используется в навигации.
object[owner] Object Владелец папки.
contents Array[Object] Массив подпапок и файлов принадлежащих этой папке.
contents[][id] String(8) Id папки
contents[][name] String Имя папки
contents[][content_type] String content_type файла
contents[][shared] Boolean Общий доступ к папке.
contents[][size] Integer Размер файла
contents[][sha1] String(40) SHA1 файла
contents[][crc32] String(8) CRC32 файла
contents[][parent_id] String(8) Id родительской папки.
contents[][sender_id] String(8) Id пользователя от которого был получен файл.
contents[][user_id] String(8) Id владельца папки или файла.
contents[][created_at] Timestamp Время создания папки или файла
contents[][updated_at] Timestamp Время последнего изменения подпапки (но нее содержимого) или файла.
contents[][is_dir] Boolean Указывает на то, что объект именно папка, а не файл.
contents[][icon] String Тип иконки для файла данного типа, весь список.
contents[][preview] String Тип превью для файла. Варианты: image и video.
contents[][unread] Boolean Свойство непрочитанности файла.
contents[][inline] Boolean Можно отображать inline.
contents[][secure_url] String Временная ссылка на скачивание.
contents[][whidden_folders] Array[String(8)] Массив ids подпапок, которые не будут отображаться при подключении по WebDAV.
contents[][whidden_files] Array[String(8)] Массив ids файлов, которые не будут отображаться при подключении по WebDAV.
contents[][ancestry] Array[Object] Массив родительских папок. Используется в навигации.

К папкам может быть предоставлен публичный доступ (публичные папки). За общий доступ отвечает аттрибут shared.

Создание

Запрос

POST /folders.json HTTP/1.1
{
  "folder": {
    "name": "New folder"
    "parent_id": "xxxxxxxx"
  }
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    "name":"New folder"
    // other attributes skipped
  }
}

Интерфейс для создание папки.

Параметры запроса

POST /folders.json

Ключ Тип Описание
folder[name] String Имя папки
folder[parent_id] String(8) ID папки в которой нужно создать папку.

Параметры ответа

Параметры ответа такие же как и при просмотре, кроме подпапок и файлов (ключ contents).

Переименование

Запрос

PATCH /folders/xxxxxxxx.json HTTP/1.1
{
  "folder": {
    "name": "New name"
  }
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    "name":"New name"
    // other attributes skipped
  }
}

Этим интерфейсом можно изменить название папки.

Параметры запроса

PATCH /folders/xxxxxxxx.json

Ключ Тип Описание
folder[name] String Имя папки

Параметры ответа

Параметры ответа такие же как и при просмотре, кроме подпапок и файлов (ключ contents).

Перемещение

Запрос

PATCH /folders/bulk.json HTTP/1.1
{
  "operation": "move",
  "folder_ids": ["xxxxxxxx", "xxxxxxxx"],
  "file_ids": ["xxxxxxxx", "xxxxxxxx"],
  "to_folder": "xxxxxxxx"
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    // other attributes skipped
  }
}

Этим интерфейсом можно переместить папки и файлы в другую папку доступную для пользователя.

Параметры запроса

PATCH /folders/bulk.json

Ключ Тип Описание
operation String Имя операции, здесь - move.
folder_ids Array[String(8)] Массив ids подпапок, которые необходимо переместить.
file_ids Array[String(8)] Массив ids файлов, которые необходимо переместить
to_folder String(8) Id папки в которую необходимо переместить.

Параметры ответа

Параметры ответа такие же как и при просмотре, кроме подпапок и файлов (ключ contents).

Копирование

Запрос

PATCH /folders/bulk.json HTTP/1.1
{
  "operation": "copy",
  "folder_ids": ["xxxxxxxx", "xxxxxxxx"],
  "file_ids": ["xxxxxxxx", "xxxxxxxx"],
  "to_folder": "xxxxxxxx"
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    // other attributes skipped
  }
}

Этим интерфейсом можно копировать папки и файлы в другую папку доступную для пользователя.

Параметры запроса

PATCH /folders/bulk.json

Ключ Тип Описание
operation String Имя операции, здесь - copy.
folder_ids Array[String(8)] Массив ids подпапок, которые необходимо скопировать.
file_ids Array[String(8)] Массив ids файлов, которые необходимо скопировать.
to_folder String(8) Id папки в которую необходимо скопировать.

Параметры ответа

Параметры ответа такие же как и при просмотре, кроме подпапок и файлов (ключ contents).

Удаление

Запрос

PATCH /folders/bulk.json HTTP/1.1
{
  "operation": "delete",
  "folder_ids": ["xxxxxxxx", "xxxxxxxx"],
  "file_ids": ["xxxxxxxx", "xxxxxxxx"]
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    // other attributes skipped
  }
}

Этим интерфейсом можно удалять папки и файлы доступные для пользователя.

Параметры запроса

PATCH /folders/xxxxxxxx.json

Ключ Тип Описание
operation String Имя операции, здесь - delete, destroy или remove.
folder_ids Array[String(8)] Массив ids подпапок, которые необходимо удалить.
file_ids Array[String(8)] Массив ids файлов, которые необходимо удалить.

Параметры ответа

Параметры ответа такие же как и при просмотре, кроме подпапок и файлов (ключ contents).

Общий доступ

Запрос

PATCH /folders/xxxxxxxx.json HTTP/1.1
{
  "folder": {
    "shared": true
  }
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    "shared": true,
    // other attributes skipped
  }
}

Этим интерфейсом можно открыть общий доступ к папке.

Параметры запроса

PATCH /folders/xxxxxxxx.json

Ключ Тип Описание
folder[shared] Boolean Общий доступ к папке

Закрыть общий доступ к папке можно передав в запросе folder[shared] = false, значение folder[allowed_wmids] в данном случае не имеет значения.

Параметры ответа

Параметры ответа такие же как и при просмотре, кроме подпапок и файлов (ключ contents).

Скачивание

Запрос

GET /z/xxxxxxxx?e=xxxxxxxxxxxx&s=xxxxxxxxxxxx HTTP/1.1

Ответ

Content-Disposition:attachment; filename=tiest-2.zip
Content-Length:43728429
Content-Type:application/zip

Параметры запроса

URL для скачивания папки определен в параметре object[secure_url] при запросе просмотре папки или в contents[][secure_url].

GET /z/folder_id/?e=xxxxxxxx&s=xxxxxxxx скачивание папки

Ключ Тип Описание
folder_id String(8) ID файла.
e String Авторизационная переменная.
s String Авторизационная переменная.

Параметры ответа

Папки скачиваются в формате zip архива.

WebDAV aттрибуты

Запрос

PATCH /folders/xxxxxxxx.json HTTP/1.1
{
  "folder": {
   "whidden_folders": ["xxxxxxxx", "xxxxxxxx"],
   "whidden_files": ["xxxxxxxx", "xxxxxxxx"]
  }
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    "whidden_folders": ["xxxxxxxx", "xxxxxxxx"],
    "whidden_files": ["xxxxxxxx", "xxxxxxxx"]
    // other attributes skipped
  }
}

Этим интерфейсом можно задать список дочерних подпапок и файлов, которые не должны отображаться при подключении по WebDAV.

Параметры запроса

PATCH /folders/xxxxxxxx.json

Ключ Тип Описание
folder[whidden_folders] Array[String(8)] Массив ids подпапок
folder[whidden_files] Array[String(8)] Массив ids подпапок

Параметры ответа

Параметры ответа такие же как и при просмотре, кроме подпапок и файлов (ключ contents).

Файлы

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

Запрос

GET /files/xxxxxxxx.json HTTP/1.1
...

Ответ

HTTP/1.1 200 OK
{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    "name":"file.png",
    "description":null,
    "content_type":"image/png",
    "shared":true,
    "size":57593,
    "sha1":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "crc32":"xxxxxxxx",
    "parent_id":"xxxxxxxx",
    "user_id":"xxxxxxxx",
    "created_at":"2015-04-01T11:23:19.770+03:00",
    "updated_at":"2015-04-01T11:23:23.527+03:00",
    "is_dir":false,
    "icon":"icon-file-image",
    "preview":"image",
    "secure_url":"/g/xxxxxxxx/xxxxx?f=file_name.png&e=xxxxx&s=xxxxx",
    "last_interaction_at":"2015-04-01T11:23:19.770+03:00",
    "inline":true
  }
}

Параметры запроса

GET /files/xxxxxxxx.json - запрос свойств файла

Параметры ответа

Ключ Тип Описание
object[id] String(8) Id файла
object[name] String Имя файла
object[description] String Описание файла
object[content_type] String Mime type файла
object[shared] Boolean Общий доступ к файлу.
object[size] Integer Размер файла.
object[sha1] String(40) SHA1 файла.
object[crc32] String(8) CRC32 файла.
object[parent_id] String(8) Id родительской папки.
object[user_id] String(8) Id владельца файла.
object[created_at] Timestamp Время создания файла
object[updated_at] Timestamp Время последнего изменения файла.
object[is_dir] Boolean Указывает на то, что объект именно папка, а не файл.
object[icon] String Тип иконки для файла данного типа, весь список.
object[preview] String Тип превью для файла. Варианты: image и video.
object[secure_url] String Временная ссылка на скачивание.
object[last_interaction_at] Timestamp Время последнего расшаривания файла.
object[inline] Boolean Можно отображать inline.

Получение ссылки на preview файла

Пример javascripts кода генерации preview ссылки

var get_preview, preview_link;

get_preview = function(object, preview_type) {
  var href, name;
  name = 'preview.' + preview_type + '.png';
  if (!!object.sha1 && object.preview === 'image') {
    href = ['/previews', object.sha1.substr(0, 2), object.sha1.substr(2, 2), object.sha1.substr(4, 40), object.id, name].join('/');
  }
  return href;
};

preview_link = get_preview(file_object, 'large');

Ссылку на preview файла можно получить по его SHA1 и ID

Cсылка имеет следующий вид /previews/sha1{0,2}/sha1{2,4}/sha1{4,40}/id/preview.preview_type.png, где

Ключ Тип Описание
id String(8) Id файла
sha1 String(40) SHA1 файла
preview_type String Тип preview. Варианты: tiny,thumb,mini,small,medium,large.

Варианты и размеры типов preview

Тип Геометрия Обрезание
tiny 30x30 Да
thumb 90x120 Да
mini 100x100 Нет
small 160x160 Нет
medium 240x240 Нет
large 750x750 Нет
poster.png XxX Нет (только для видео файлов)
mp4 XxX Нет (только для видео файлов)

Загрузка файлов

Запрос

POST /fast_upload?parent_id=xxxxxxxx HTTP/1.1
Content-Type:multipart/form-data; boundary=xxxxxxxxxxxx
...

Ответ

HTTP/1.1 200 OK
{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    "name":"file.png",
    "description":null,
    "content_type":"image/png",
    "shared":false,
    "size":57593,
    "sha1":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "crc32":"xxxxxxxx",
    "parent_id":"xxxxxxxx",
    "user_id":"xxxxxxxx",
    "created_at":"2015-04-01T11:23:19.770+03:00",
    "updated_at":"2015-04-01T11:23:23.527+03:00",
    "is_dir":false,
    "icon":"icon-file-image",
    "preview":"image",
    "secure_url":"/g/xxxxxxxx/xxxxx?f=file_name.png&e=xxxxx&s=xxxxx",
    "last_interaction_at":"2015-04-01T11:23:19.770+03:00",
    "inline":true
  }
}

Параметры запроса

POST /fast_upload?parent_id=xxxxxxxx , где parent_id - ID папки в которую загружается файл.

Существует возможность загрузки файла в поддиректорию, скрытой дирректорию .outgoing, для этого необходимо отправить запрос следующего вида:

POST /fast_upload?t=xxxxxxxx , где t - Unix Timestamp , типа Integer.

При такой загрузке файла, автоматически создастся директория, с именем согласно Unix Timestamp, если такая не существовала, иначе загрузка произойдет в уже существующую директорию.

Дополнительно поддерживается опциональный параметр make_preview (Boolean, по умолчанию true):

POST /fast_upload?parent_id=xxxxxxxx&make_preview=false

При make_preview=false для файла не будет запущена генерация превью, при этом проверка на вирусы выполняется в обычном режиме. Факт осознанного отключения превью сохраняется в свойствах файла. Значение по умолчанию (true либо отсутствие параметра) соответствует прежнему поведению — превью генерируется.

Параметры ответа

Такии же как при получении свойств файла

Переименование

Запрос

PATCH /files/xxxxxxxx.json HTTP/1.1
{
  "file": {
    "name": "yyyyyyyy"
  }
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    "name": "yyyyyyyy",
    // other attributes skipped
  }
}

Параметры запроса

PATCH /files/xxxxxxxx.json - изменение свойств файла

Ключ Тип Описание
file[name] String Имя файла

Параметры ответа

Такии же как при получении свойств файла

Перемещение

Перемещение файлов описано в разделе “перемещение папок и файлов

Копирование

Копирование файлов описано в разделе “копирование папок и файлов

Общий доступ

Запрос

PATCH /files/xxxxxxxx.json HTTP/1.1
{
  "file": {
    "shared": true
  }
}

Ответ

{
  "code":200,
  "object":{
    "id":"xxxxxxxx",
    "shared": true,
    // other attributes skipped
  }
}

Этим интерфейсом можно открыть и закрыть общий доступ к файлу

Параметры запроса

PATCH /files/xxxxxxxx.json - изменение свойств файла

Ключ Тип Описание
file[shared] Boolean Общий доступ к файлу

Параметры ответа

Такии же как при получении свойств файла

Скачивание

Запрос

GET /g/xxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx?f=file_name.png&e=xxxxxxxx&s=xxxxxxxx HTTP/1.1

Ответ

Content-Disposition:attachment; filename="file_name.png"

Параметры запроса

URL для скачивания файла определен в параметре object[secure_url] при запросе получении свойств файла или в contents[][secure_url] при запросе просмотр папки

GET /g/file_id/sha1?f=file_name.png&e=xxxxxxxx&s=xxxxxxxx&inline=true скачивание файла

Ключ Тип Описание
file_id String(8) ID файла.
sha1 String(40) SHA1 файла.
e String Авторизационная переменная.
s String Авторизационная переменная.
inline Boolean Необязательная переменная указывает на то будет ли отдаваться файл inline

Параметры ответа

HTTP Header Content-Disposition зависит от того как был запрошен файл inline или нет

Удаление

Удаление файлов описано в разделе “Удаление папок и файлов

Аккаунт

Настройки пользователя

Запрос

GET /account.json HTTP/1.1
...

Ответ

HTTP/1.1 200 OK
{
  "id":"vx7hWgVI",
  "name":"Vasiliy"
  "email":"ab@ab.ru"
  "limit_count":10000,
  "limit_size":10737418240,
  "volume_count":0,
  "volume_size":0,
  "prefers_time_zone":"Moscow",
  "prefers_webdav_enabled":false,
  "prefers_show_hidden":false,
  "prefers_disable_unauth_sender":true,
  "prefers_show_hidden_webdav":true,
  "unread_count":0
}

Этим запросом вы можете получить все настройки пользователя, а также лимиты и текущие состояния пользователя.

Параметры запроса

GET /account.json

Параметры ответа

Ключ Тип Описание
id String(8) Id пользователя
name String Имя пользователя
email String E-mail пользователя
limit_count Integer Общий лимит на кол-во файлов для пользователя. По умолчанию 10000.
limit_size Integer Общий лимит по объему для пользователя, в байтах. По умолчанию 10737418240 (10Гб).
volume_count Integer Количество файлов у пользователя в настоящий момент.
volume_size Integer Текущий занятый объем пользователем, в байтах.
prefers_time_zone String Временная зона пользователя. По умолчанию Moscow
prefers_webdav_enabled Boolean Подключения по WebDAV. По умолчанию false.
prefers_show_hidden Boolean Отображать скрытые(начинающиеся с точки) файлы и папки. По умолчанию false.
prefers_show_hidden_webdav Boolean Отображать скрытые(начинающиеся с точки) файлы и папки при подключении по WebDAV. По умолчанию true.
prefers_disable_unauth_sender Boolean Принимать файлы от неавторизованных корреспондентов. По умолчанию false.
unread_count Integer Количество непрочитанных файлов для пользователя в настоящий момент.

Изменение настроек

Запрос

PATCH /account.json HTTP/1.1
{
  "user": {
    "prefers_webdav_enabled":true,
  }
}

Ответ

HTTP/1.1 200 OK
{
  "prefers_webdav_enabled":true,
  // other attributes skipped
}

Этим запросом вы можете изменить некоторые настройки пользователя. Доступные настройки указаны в параметрах запроса.

Параметры запроса

PATCH /account.json

Ключ Тип Описание
user[prefers_time_zone] String Временная зона пользователя. По умолчанию Moscow
user[prefers_webdav_enabled] Boolean Подключения по WebDAV. По умолчанию false.
user[prefers_show_hidden] Boolean Отображать скрытые(начинающиеся с точки) файлы и папки. По умолчанию false.
user[prefers_show_hidden_webdav] Boolean Отображать скрытые(начинающиеся с точки) файлы и папки при подключении по WebDAV. По умолчанию true.
user[prefers_disable_unauth_sender] Boolean Принимать файлы от неавторизованных корреспондентов. По умолчанию false.

Параметры ответа

Параметры ответа точно такие же как и при запросе настроек пользователя.

WebDAV API

Документация к WebDAV API отсутствует, поскольку API работает почти в полном соответстии с RFC 4918.

Для авторизации используется email и пароль.

Коды ошибок

Запрос

GET /files/xxxxx.json HTTP/1.1

Ответ

HTTP/1.1 404 Not Found
{
  "code":404,
  "reason":"file",
  "message":"Файл не найден"
}

Смотрите примеры и таблицу кодов ответа сервера.

Error Code Значение
400 Bad Request – Неправильный запрос, проверьте параметры запроса.
401 Unauthorized – Пользователь не авторизовался или его сессия протухла.
403 Forbidden – Недостаточно прав.
404 Not Found – Запрашиваемый ресурс не найден.
405 Method Not Allowed – Метод запроса не разрешен.
406 Not Acceptable – Метод запрос не поддерживается.
429 Too Many Requests – Слишком много запросов. Нео, притормози!
500 Internal Server Error – Ошибка на сервере. Повторите операцию позже.
503 Service Unavailable – Сервис временно не доступен. Повторите операцию позже.