Требования к API внешней ЭБС, для интеграции с модулем "Библиотека ресурсов 3КL" (материал для разработчиков)
По вопросам интеграции и сотрудничества обращайтесь в ООО «Открытые технологии».
1. Использующиеся термины
2. Введение
3. Методы интеграции
3.1. Авторизация
3.1.1. Общий принцип
3.1.2. Пример запроса с комментариями по возможностям реализации
3.2. Получение категорий
3.2.1. Общий принцип
3.2.2. Пример запроса с комментариями по возможностям реализации
3.3. Получение ресурсов по категории
3.3.1. Пример запроса с комментариями по возможностям реализации
3.4. Поиск ресурсов
3.4.1. Пример запроса с комментариями по возможностям реализации
3.5. Получение контента ресурса
3.5.1. Возможны три режима отображения
3.5.2. Пример запроса с комментариями по возможностям реализации
4. Дополнительная информация
1. Использующиеся термины
- провайдер - организация, предоставляющая api для интеграции с СДО;
- ресурс - книга, статья, журнал, документ, предназначенный для отображения в результате интеграции в модуле «Библиотека ресурсов 3КL»;
- источник - экземпляр интеграции, реализующий комплекс возможностей, предоставляемых провайдером своему клиенту для доступа к ресурсам;
- категория - раздел, каталог, предоставляемый источником и содержащий в себе свойственные ему ресурсы;
2. Введение
Модуль СДО «Библиотека ресурсов 3КL» предоставляет возможность преподавателю найти ресурс в одном из настроенных администратором СДО источников, для последующего отображения ресурса учащимся. Преподаватель выполняет выбор ресурса путём выбора категории и просмотра списка ресурсов, содержащихся в категории, либо путём ввода поискового запроса и просмотра списка результатов поиска.
Ниже описаны методы, необходимые для реализации наиболее распространенного подхода интеграции между модулем СДО «Библиотека ресурсов 3КL» и внешними источниками. С их помощью возможно сформировать базовый набор функций, необходимых для работы с модулем.
Приведенные примеры не являются обязательными требованиями, они содержат перечень данных, необходимых по нашему опыту для реализации комфортной работы с интегрированной системой.
3. Методы интеграции
3.1. АВТОРИЗАЦИЯ
Реализовывается провайдером при необходимости предоставлять ресурсы ограниченному списку пользователей.
3.1.1. Общий принцип
- администратору СДО известны реквизиты интеграции (секретный ключ или пара логин/пароль), которые он настраивает для подключения к источнику;
- перед обращением к источнику, СДО делает запрос в источник по предоставленному источником api, передавая реквизиты интеграции;
- источник возвращает токен авторизации для использования в последующих запросах;
3.1.2. Пример запроса с комментариями по возможностям реализации
Запрос:
ENDPOINT
- /api/auth
POST
- username - логин для авторизации
- password - пароль для авторизации
Ответ:
В ответ приходит объект JSON, содержащий результат обработки запроса и токен авторизации:
- (bool) success - результат обработки запроса
- (string) error - описание ошибки (если результат обработки запроса не был успешным)
- (string) token - токен авторизации для использования в последующих запросах
3.2. ПОЛУЧЕНИЕ КАТЕГОРИЙ
Преподаватель в СДО производит выбор ресурса, к которому планирует предоставить доступ учащемуся в курсе.
Одним из сценариев выбора ресурса является выбор из списка ресурсов, принадлежащих выбранной категории. Если источник имеет древовидную структуру хранения ресурсов, необходимо реализовать возможность получения списка категорий с её использованием.
3.2.1. Общий принцип:
- СДО обращается к источнику, запрашивая список категорий, являющихся дочерними для категории, переданной параметром;
- в запросе передается токен авторизации, полученный ранее от источника (если требуется источником);
- источник возвращает список категорий, дочерних от категории, переданной параметром.
3.2.2. Пример запроса с комментариями по возможностям реализации:
Запрос:
ENDPOINT
- /api/categories
HEADERS
- token - токен авторизации
GET
- idCategory - идентификатор родительской категории, чьих потомков необходимо получить. Значение null интерпретируется как запрос категорий верхнего уровня (без родителя).
Ответ:
В ответ приходит объект JSON, содержащий результат обработки запроса и список категорий, найденных по запросу:
- (bool) success - результат обработки запроса
- (string) error - описание ошибки (если результат обработки запроса не был успешным)
- (array) items - массив, содержащий объекты со сведениями о найденных категориях (пустой массив, если категорий не было найдено).
Объекты категорий должны содержать:
- идентификатор категории,
- наименование категории,
- сведения о наличии потомков в категории.
Объект категории может содержать любые дополнительные сведения о категории.
3.3. ПОЛУЧЕНИЕ РЕСУРСОВ ПО КАТЕГОРИИ
Преподаватель в СДО производит выбор ресурса, к которому планирует предоставить доступ учащемуся в курсе.
Одним из сценариев выбора ресурса является выбор из списка ресурсов, принадлежащих выбранной категории. Если источник имеет структуру хранения ресурсов, подразумевающую наличие категорий, необходимо реализовать возможность получения списка ресурсов с её использованием.
3.3.1. Пример запроса с комментариями по возможностям реализации
Запрос:
ENDPOINT
- /api/resources
HEADERS
- token - токен авторизации
GET
- idCategory - идентификатор категории
- limit - количество ресурсов необходимое для предоставления в результатах запроса;
- offset - количество ресурсов для смещения перед осуществлением выборки; вместо offset также допустимо принимать параметр page (страница) для организации смещения по формуле ((page-1)* limit)
Ответ:
В ответ приходит объект JSON, содержащий результат обработки запроса и список ресурсов, найденных по запросу:
- (bool) success - результат обработки запроса
- (string) error - описание ошибки (если результат обработки запроса не был успешным)
- (array) items - массив, содержащий объекты со сведениями о найденных ресурсах (пустой массив, если ресурсов не было найдено).
- (int) total - общее количество результатов по запросу (до применения смещения offset и ограничения limit)
Объекты ресурсов должны содержать:
- уникальный идентификатор ресурса
- заголовок ресурса
Объекты ресурсов могут содержать любую дополнительную информацию о ресурсе. Наиболее распространенные сведения для примера:
- описание ресурса
- авторы
- isbn
- издательство
- количество страниц
- год выпуска
- url-адрес ресурса на веб-сайте провайдера
- url-адрес с изображением обложки ресурса
3.4. ПОИСК РЕСУРСОВ
Преподаватель в СДО производит выбор ресурса, к которому планирует предоставить доступ учащемуся в курсе.
Одним из сценариев выбора ресурса является выполнение поиска по поисковому запросу.
Если источник имеет возможность предоставить результаты поиска ресурсов по поисковому запросу, необходимо реализовать возможность получения списка ресурсов таким образом.
3.4.1. Пример запроса с комментариями по возможностям реализации
Запрос:
ENDPOINT
- /api/resources
HEADERS
- token - токен авторизации
GET
- query - поисковая фраза; провайдеру рекомендуется обрабатывать поисковую фразу не только для полнотекстового поиска по содержимому ресурса, но и для поиска по заголовку ресурса, isbn, автору, идентификатору ресурса; при отсутствии этого параметра запрос воспринимается как попытка получить все ресурсы из категории (см. "ПОЛУЧЕНИЕ РЕСУРСОВ ПО КАТЕГОРИИ")
- idCategory - идентификатор категории, в пределах которой необходимо выполнять поиск ресурсов по поисковой фразе; если источник поддерживает древовидную структуру хранения ресурсов, мы рекомендуем реализовать поддержку этого параметра; при отсутствии параметра должен выполняться поиск по всему источнику;
- limit - количество ресурсов необходимое для предоставления в результатах запроса;
- offset - количество ресурсов для смещения перед осуществлением выборки; вместо offset также допустимо принимать параметр page (страница) для организации смещения по формуле ((page-1)* limit)
Ответ:
В ответ приходит объект JSON, содержащий результат обработки запроса и список ресурсов, найденных по запросу:
- (bool) success - результат обработки запроса
- (string) error - описание ошибки (если результат обработки запроса не был успешным)
- (array) items - массив, содержащий объекты со сведениями о найденных ресурсах (пустой массив, если ресурсов не было найдено).
- (int) total - общее количество результатов по запросу (до применения смещения offset и ограничения limit)
Объекты ресурсов должны содержать:
- уникальный идентификатор ресурса
- заголовок ресурса
Объекты ресурсов могут содержать любую дополнительную информацию о ресурсе. Наиболее распространенные сведения для примера:
- отрывок текста, в котором найдена поисковая фраза
- описание ресурса
- авторы
- isbn
- издательство
- количество страниц
- год выпуска
- url-адрес ресурса на веб-сайте провайдера
- url-адрес с изображением обложки ресурса
3.5. ПОЛУЧЕНИЕ КОНТЕНТА РЕСУРСА
Преподаватель выбрал ресурс, к которому планирует предоставить доступ учащемуся в курсе.
Учащийся открывает модуль «Библиотека ресурсов 3КL» с ресурсом, настроенным ранее преподавателем.
Система должна отобразить ресурс учащемуся.
3.5.1. Возможны три режима отображения:
- встроенный контент. Модуль «Библиотека ресурсов 3КL» отобразит учащемуся плеер. Формирование кода плеера производится либо по образцу от источника (в образец подставляются параметры ресурса), либо источник должен предоставить готовый html-код плеера по запросу. Получившийся код отображается в СДО как есть, соответственно необходимо обеспечить использование только полных ссылок в контенте.
- транслированный контент. Модуль «Библиотека ресурсов 3КL» отображает html-код ресурса, предоставленный источником, предварительно заменяя оригинальные ссылки, ведущие на материалы источника (не внешние) содержащиеся в контенте ресурса, на ссылку до специального скрипта, выполняющего маршрутизацию. Скрипт маршрутизации принимает в качестве параметра ссылку до источника и выполняет запрос к источнику на получение контента, передавая токен авторизации. Это позволяет организовать учащимся в СДО доступ к закрытому контенту без публикации ключей авторизации. Доступ предоставляется только пользователям, имеющим доступ к соответствующему элементу курса (авторизованы, подписаны на курс, дошли до изучения ресурса).
- ссылка со сквозной авторизацией. При переходе учащегося к ресурсу, модуль «Библиотека ресурсов 3КL» запрашивает у источника предавторизованную (содержащую токен авторизации) ссылку на ресурс по идентификатору ресурса. Минусом данного режима является переход на другой сайт и изменение внешнего вида системы.
3.5.2. Пример запроса ресурса с комментариями по возможностям реализации
Запрос:
ENDPOINT
- /api/resource_content
HEADERS
- token - токен авторизации
GET
- id - идентификатор ресурса
- user - данные, идентифицирующие пользователя (для статистики)
- course - данные, идентифицирующие курс (для статистики)
- module - данные, идентифицирующие элемент курса (для статистики)
- session - данные, идентифицирующие сессию (для статистики)
Ответ:
В ответ приходит объект JSON, содержащий результат обработки запроса и данные о ресурсе:
- (bool) success - результат обработки запроса
- (string) error - описание ошибки (если результат обработки запроса не был успешным)
- (string) content - либо html-код плеера, либо html-код ресурса (контент), либо предавторизованная ссылка (в зависимости от необходимого режима отображения)
Ответ может также содержать другие данные, если выбран режим отображения, подразумевающий необходимость подставлять в образец кода плеера данные об отображаемом ресурсе.
4. ДОПОЛНИТЕЛЬНАЯ ИНФОРМАЦИЯ
Источник может предоставить дополнительные файлы, необходимые html-плееру, например, скрипты javascript или стили css.
Они могут быть переданы двумя способами:
- источник может вернуть предавторизованные ссылки (могут содержать дополнительные ключи прямо в URL, не должны требовать авторизации), которые модуль «Библиотека ресурсов 3КL» подставит в html-код.
- источник может предоставить API для запроса этих файлов. Модуль «Библиотека ресурсов 3КL» странслирует эти файлы. В этом случае, система проверит, что пользователь авторизован и имеет доступ к просмотру конкретного ресурса.