REST API для загрузки файлов ОЭД (beta)
REST API - как определенный интерфейс, через который происходит взаимодействие посредством определенного набора HTTP-запросов, а также получение HTTP-ответов определенной структуры в формате JSON.
Все запросы осуществляются с использованием протокола HTTPS с применением протокола защиты транспортного уровня (TLS) 1.3.
В настоящий момент rest-api для ОЭД находится в стадии тестирования.
Типовое соглашение и спецификация для телевизионных СМИ для использования API
Список полей карточки материала
Ограничения на количество запросов
Создать карточку материала.
Загрузить файл в карточку.
Отправить карточку на проверку.
Процесс аутенитфикации возможен при наличии персонального ключа (ApiKey) и секретного ключа (SecretKey) на основе которого вычисляется RequestHash, которым, в дальнейшем, должен быть подписан каждый запрос к API.
Данные ApiKey и RequestHash необходимо оправлять в виде HTTP-заголовков в каждом запросе к сервису.
Заголовки запроса, необходимые для аутентификации "ApiKey:4c832ce76e40bb7fdb776fcb328981d4d4c58f5c" "RequestHash:1216dbef35ae3ea74ab197a9cc23882e91d79209a0773703798a498599d4b85d" |
Получить секретный ключ (SecretKey) можно на специальной странице, ссылку на которую можно получить у сотрудника ОЕДа. Срок действия ссылки - 3 суток. После истечения этого времени ее необходимо получить заново.
С помощью SecretKey, необходимо генерировать хеш запроса (RequestHash), который и предавать вместе с данными запроса. На сервере , с помощью секретного ключа проверяются переданные данные.
Для генерации RequestHash необходимо использовать метод HMAC с алгоритмом ‘sha256’ и генерировать строку содержащую хеш-код в шестнадцатеричной кодировке в нижнем регистре.
При загрузке файла, тело файла не добавляем в строку для хеширования.
Вычисление Request-hash Строка для хеширования = <RequestURL> + <Тело запроса> + <Заголовки> RequestURL - относительный Url запроса без имени хоста со всеми параметрами строки запроса Тело запроса - сериализованное в json тело запроса перед отправкой Заголовки - ApiKey, FileHash (в случае отправки файла)
Части строки конкатенируются без разделителей.
Пример строки для хеширования Запрос для создания карточки материала: curl -X POST -H "ApiKey:test" -H "RequestHash:1216dbef35ae3ea74ab197a9cc23882e91d79209a0773703798a498599d4b85d" https://oed.gtrf.ru/api/materials/ -d '{"title":"Test Send materials","date_aired":"20.10.2016 16:10:33","broadcast_country_id":"1","Languages":["42"]}’
Сторока для хеширования: toHash = ‘/api/materials{"title":"Test Send materials","date_aired":"20.10.2016 16:10:33","broadcast_country_id":"1","Languages":["42"]}test’ RequestHash = 1216dbef35ae3ea74ab197a9cc23882e91d79209a0773703798a498599d4b85d |
Метод |
URL |
Описание |
Пример curl-запроса |
GET |
/api/languages |
Справочник "Языки" |
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/languages |
GET |
/api/countries |
Справочник "Страны вещания" |
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/countries |
GET |
/api/materials/
/api/materials/index/page/pagenum |
Просмотр списка карточек материалов Постраничный вывод материалов |
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/index/page/2 |
GET |
/api/files |
Просмотр списка загруженных файлов |
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/files/ |
DELETE |
/api/files/fileId |
Удаление загруженного файла |
curl -X DELETE -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/files/12345 |
POST |
/api/files? material_id=materialId& filename=fileName |
Загрузка файла в карточку материала |
curl -X POST -H "ApiKey:test" -H "RequestHash:test" -H “FileHash:df1555ec0c2d7fcad3a03770f9aa238a“ ‘https://oed.gtrf.ru/api/files/?material_id=12345&filename=2.mpeg’ --data-binary @2.mpeg |
POST |
/api/materials |
Создание карточки материала |
curl -X POST -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/ -d '{"title":"testPOST$", "date_aired":"11.08.2016 00:00:00", "broadcast_country_id":"1","Languages":[“42”,”23”,”1”]}' |
DELETE |
/api/materials |
Удаление карточки материала |
curl -X DELETE -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/12345 |
PATCH |
/api/materials/materialId |
Изменение карточки материала |
curl -X PATCH -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/12345 -d '{"director":"Режиссер","anons":"Описание материала","guests":"Гость","title":"test PATCH"}' |
GET |
/api/materials/materialId |
Просмотр карточки материала |
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/12345 |
POST |
/api/materials/send/materialId |
Отправка материала на проверку |
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/send/12345/ |
DELETE |
/api/materials/deleteIn/materialId |
Удаление файла (всех файлов) из карточки материала |
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/deleteIn/12345/ |
GET |
/api/materials/foreign_id/foreignId |
Получение материала по внешнему ключу |
curl -H "ApiKey:test" -H "RequestHash:test" https://oed.gtrf.ru/api/materials/foreign_id/12345 |
Пример запроса для создания карточки материала
POST /api/materials/ |
Данные для заполнения полей broadcast_country_id и Languages получаются из соответствующих справочников.
Метод возвращает созданную карточку, в заголовке Location url созданной карточки.
В случае ошибок валидации данных, возвращает код 422 и список полей и описание ошибок в теле ответа.
Поле |
Тип |
Формат (Размер) |
Обяз. |
Описание |
title |
Строка |
255 |
+ |
Заголовок |
date_aired |
Дата Время |
dd.MM.yyyy HH:mm:ss |
+ |
Дата и время первого выхода в эфир |
broadcast_country_id |
Число |
ид из справочника Countries |
+ |
Страна вещания |
Languages |
Массив |
Ид языков из справочника Languages Пример: [ "42",”1” ] |
+ |
Языки |
date_air_end |
Дата |
dd.MM.yyyy |
|
Дата выхода в эфир последнего выпуска, если материал содержит более одного выпуска |
vendor |
Строка |
255 |
|
Производитель (если по заказу) |
author |
Строка |
255 |
|
Автор(ы) сценария |
composer |
Строка |
255 |
|
Композитор |
director |
Строка |
255 |
|
Режиссер |
fragments |
Текст |
65535 |
|
Используемые фрагменты |
presenters |
Текст |
65535 |
|
Ведущие |
guests |
Текст |
65535 |
|
Гости |
anons |
Текст |
5000 |
|
Аннотация |
foreign_id |
Строка |
255 |
Внешний ключ пользователя, уникальный для текущего пользователя |
Пример ответа при создании карточки материала:
HTTP/1.1 201 Created |
У материала может быть несколько состояний (статусов), в зависимости от которых с материалами можно проводить различные действия.
Код |
Статус |
Описание |
Действия |
1 |
Новый |
Создана новая карточка. Файл не загружен. |
Доступны все действия корме отправки на проверку |
2 |
Загружен |
В карточку материала загружен файл |
Все действия |
3 |
Отправлен |
Материал отправлен на проверку |
Только просмотр |
4 |
Принят |
Материал принят службой ОЭД |
Только просмотр |
5 |
Отклонен |
Материал отклонен службой ОЭД |
Удаление, редактирование, удаление файла |
Внешний уникальный ключ возможно применять для контроля уникальности материалов на строне клиента. Поле необязательное. Также есть возможность получать карточку материала по этому ид. Примеры запросов и возвращаемых ошибок см. в соотв. таблицах.
Код |
Описание |
dateFalseFormat |
Неправильный формат даты |
stringLengthTooLong |
Днинна строки превышает допустимую |
notInArray |
Значение не находится в списке допустимых. |
isEmpty |
Пустое значение недопустимо. |
not_in |
Дата выхода звгружаемого материала не входит в срок действия соглашений |
not_unique |
Запись с таким внешним ключом (foreign_id) для этого пользователя существует |
В теле запроса передаем только те поля, которые необходимо изменить. Тело запроса обязательно.
Можно редактировать материалы со статусом новый, загружен, отклонен
Метод возвращает отредактированную карточку
PATCH /api/materials/:id |
Обращение к методу возвращает код 204, в случае успешного удаления.
Нельзя удалить материалы со статусом отправлен и принят
DELETE /api/materials/:id |
Для материалов доступны дополнительные параметры строки запроса. Для справочников (языки и страны) данные параметры не доступны
page - номер страницы, по умолчанию на странице 100 элементов,
per_page - размер страницы
order - сортировка по полю, "-" - обратный порядок.
Пример:
Получаем втораую страницу, на странице 100 элементов отсортировано по полю в обратном порядке id.
GET /api/materials/index/page/2/per_page/100/order/-id |
В ответе получаем даанные о колочиестве материалов, и сами материалы в массиве data.
{ "data":[{},...], "current_page":2, "pages":4, "per_page":100, "count":325 } |
Параметр |
Обязателен |
Описание |
Где передается |
FileHash |
+ |
MD5-хэш файла |
В заголовке |
material_id |
+ |
Ид материала в который загружается файл |
В строке запроса |
filename |
Имя файла |
В строке запроса |
|
@FILE |
+ |
Тело файла |
В теле запроса |
Перед загрузкой файла, необходимо создать карточку материала. Для прикрепления файла к карточке материала, необходимо добавить в качестве параметров запроса id материала и название файла (необязательный). В случае, если карточка с таким номером не найдена, вернется код ошибки 404 'Material not found'.
Для проверки целостности отправленного файла, в заголовке запроса должен быть праметр FileHash - MD5-хэш файла, используя » алгоритм MD5 RSA. Если отправленное значение этого не совпадет со значением, вычисляемом на сервере вернется ошибка 400 'Integrity verification failed'
Нельзя загружать файлы в карточки со статусом принят или отправлен
POST /api/files?material_id=12345&filename=video.mp4 HTTP/1.1 FileHash:df1555ec0c2d7fcad3a03770f9aa238a |
Если файл загружен успешно, сервер возвращает HTTP-код 201 Created с метаданными записи и загруженного файла.
Обратите внимание, если файл загружен без ошибок, но поля файла, такие как duration, bitrate, container пусты, то возможно файл поврежден и необходимо его проверить и загрузить его повторно. Или обратиться в службу поддержки.
HTTP/1.1 201 Created |
Удалить файл из карточки можно или по ид карточки материала или по ид файла. Нельзя удалять файлы из отправленных и принятых материалов.
код |
название |
описание |
400 |
Integrity verification failed |
Хеш файла не совпадает |
404 |
Material not found |
Не найден материал к которому должен быть прикреплен файл |
406 |
Material not editable |
Материал нельзя редактировать: удалени и отправлен на проверку |
422 |
File format error |
Недопустимый формат файла |
Чтобы обеспечить бесперебойное обслуживание пользователей, мы ограничиваем скорость отправки запросов, используя алгоритм leaky bucket. Этот механизм позволяет избежать ситуаций, когда вредоносное или некорректно работающее приложение вызывает ошибку отказа в обслуживании для остальных клиентов.
Если будет превышено частотное ограничение, сервер вернет ошибку с кодом 429: "Too Many Requests".
Заголовки, информирующие об ограничениях:
X-Rate-Limit-Limit: Максимальное количество запросов за период
X-Rate-Limit-Remaining: Количество оставшихзя запросовзв текущий период
X-Rate-Limit-Reset: количество секунд ожидания до возобновления лимита до максимума
200: OK. Все сработало именно так, как и ожидалось.
201: Ресурс был успешно создан в ответ на POST-запрос. Заголовок Location содержит URL, указывающий на только что созданный ресурс.
204: Запрос обработан успешно, и в ответе нет содержимого (для запроса DELETE, например).
304: Ресурс не изменялся. Можно использовать закэшированную версию.
400: Неверный запрос. Может быть связано с разнообразными проблемами на стороне пользователя, такими как неверные JSON-данные в теле запроса, неправильные параметры действия, и т.д.
401: Аутентификация завершилась неудачно.
403: Аутентифицированному пользователю не разрешен доступ к указанной точке входа API.
404: Запрошенный ресурс не существует.
405: Метод не поддерживается. Сверьтесь со списком поддерживаемых HTTP-методов в заголовке Allow.
406: Действие невозможно, например нельзя изменять объект.
415: Не поддерживаемый тип данных. Запрашивается неправильный тип данных или номер версии.
422: Проверка данных завершилась неудачно (в ответе на POST-запрос, например). Подробные сообщения об ошибках смотрите в теле ответа.
429: Слишком много запросов. Запрос отклонен из-за превышения ограничения частоты запросов.
500: Внутренняя ошибка сервера. Возможная причина — ошибки в самой программе.
503: Cервер временно не имеет возможности обрабатывать запросы по техническим причинам (обслуживание, перегрузка и прочее). В поле RetryAfter заголовка сервер может указать время, через которое клиенту рекомендуется повторить запрос.