Требования к API внешней ЭБС, для интеграции с модулем "Библиотека ресурсов" (материал для разработчиков)

Алексей Дьяченко
2023-02-27 13:55
Этот материал предназначен для разработчиков ЭБС и библиотек контента, которые планируют интеграцию своих систем с модулем "Библиотека ресурсов" в СЭО 3KL. Такая интеграция позволит разработчикам электронных курсов в СЭО 3KL бесшовно использовать материалы из данного внешнего источника  без их прямого копирования в СЭО 3KL.
По вопросам интеграции и сотрудничества обращайтесь в ООО "Открытые технологии".
В данной статье содержатся общие требования к API внешней ЭБС, необходимые для интеграции. Поскольку под каждую внешнюю ЭБС разработчики ООО "Открытые технологии" пишут отдельный драйвер, возможны вариации в реализации API (структуре и названиях запросов, названии переменных и пр.) Главное, чтобы API так или иначе реализовывало следующие возможности: запрос списка подкатегорий заданной категории (если ЭБС вообще поддерживает древовидную иерархию), поиск ресурса по поисковой строке (и, опционально, идентификатору категории), получение контента ресурса для встраивания в одном из трех вариантов: код для встраивания, транслируемый файл (обычно используется для картинок и дополнительных файлов), предавторизованная ссылка для просмотра ресурса конкретным пользователем.

​Использующиеся термины

  • провайдер - организация, предоставляющая api для интеграции с СДО;

  • ресурс - книга, статья, журнал, документ, предназначенный для отображения в результате интеграции в модуле "Библиотека ресурсов";

  • источник - экземпляр интеграции, реализующий комплекс возможностей, предоставляемых провайдером своему клиенту для доступа к ресурсам;

  • категория - раздел, каталог, предоставляемый источником и содержащий в себе свойственные ему ресурсы;

​Введение

Модуль СДО "Библиотека ресурсов" предоставляет возможность преподавателю найти ресурс в одном из настроенных администратором СДО источников, для последующего отображения ресурса учащимся.
Преподаватель выполняет выбор ресурса путём выбора категории и просмотра списка ресурсов, содержащихся в категории, либо путём ввода поискового запроса и просмотра списка результатов поиска.

Ниже описаны методы, необходимые для реализации наиболее распространенного подхода интеграции между модулем СДО "Библиотека ресурсов" и внешними источниками. С их помощью возможно сформировать базовый набор функций, необходимых для работы с модулем.
Приведенные примеры не являются обязательными требованиями, они содержат перечень данных, необходимых по нашему опыту для реализации комфортной работы с интегрированной системой.

​Методы интеграции

​АВТОРИЗАЦИЯ

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

​Общий принцип

  • администратору СДО известны реквизиты интеграции (секретный ключ или пара логин/пароль), которые он настраивает для подключения к источнику;

  • перед обращением к источнику, СДО делает запрос в источник по предоставленному источником api, передавая реквизиты интеграции;

  • источник возвращает токен авторизации для использования в последующих запросах;

​Пример запроса с комментариями по возможностям реализации

ENDPOINT
    - /api/auth
POST
    - username - логин для авторизации
    - password - пароль для авторизации
ОТВЕТ
    В ответ приходит объект JSON, содержащий результат обработки запроса и токен авторизации:
    - (bool) success - результат обработки запроса
    - (string) error - описание ошибки (если результат обработки запроса не был успешным)
    - (string) token - токен авторизации для использования в последующих запросах

​ПОЛУЧЕНИЕ КАТЕГОРИЙ

Преподаватель в СДО производит выбор ресурса, к которому планирует предоставить доступ учащемуся в курсе.
Одним из сценариев выбора ресурса является выбор из списка ресурсов, принадлежащих выбранной категории.
Если источник имеет древовидную структуру хранения ресурсов, необходимо реализовать возможность получения списка категорий с её использованием.

​Общий принцип:

    - СДО обращается к источнику, запрашивая список категорий, являющихся дочерними для категории, переданной параметром;
    - в запросе передается токен авторизации, полученный ранее от источника (если требуется источником);
    - источник возвращает список категорий, дочерних от категории, переданной параметром;

​Пример запроса с комментариями по возможностям реализации:

ENDPOINT
    - /api/categories
HEADERS
    - token - токен авторизации
GET
    - idCategory - идентификатор родительской категории, чьих потомков необходимо получить. Значение null интерпретируется как запрос категорий верхнего уровня (без родителя).
ОТВЕТ
    В ответ приходит объект JSON, содержащий результат обработки запроса и список категорий, найденных по запросу:
    - (bool) success - результат обработки запроса
    - (string) error - описание ошибки (если результат обработки запроса не был успешным)
    - (array) items - массив, содержащий объекты со сведениями о найденных категориях (пустой массив, если категорий не было найдено).
    Объекты категорий должны содержать:
    - идентификатор категории, 
    - наименование категории, 
    - сведения о наличии потомков в категории.
    Объект категории может содержать любые дополнительные сведения о категории.

​ПОЛУЧЕНИЕ РЕСУРСОВ ПО КАТЕГОРИИ

Преподаватель в СДО производит выбор ресурса, к которому планирует предоставить доступ учащемуся в курсе.
Одним из сценариев выбора ресурса является выбор из списка ресурсов, принадлежащих выбранной категории.
Если источник имеет структуру хранения ресурсов, подразумевающую наличие категорий, необходимо реализовать возможность получения списка ресурсов с её использованием.

​Пример запроса с комментариями по возможностям реализации:

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-адрес с изображением обложки ресурса

​ПОИСК РЕСУРСОВ

Преподаватель в СДО производит выбор ресурса, к которому планирует предоставить доступ учащемуся в курсе.
Одним из сценариев выбора ресурса является выполнение поиска по поисковому запросу.
Если источник имеет возможность предоставить результаты поиска ресурсов по поисковому запросу, необходимо реализовать возможность получения списка ресурсов таким образом.

​Пример запроса с комментариями по возможностям реализации:

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-адрес с изображением обложки ресурса

​ПОЛУЧЕНИЕ КОНТЕНТА РЕСУРСА

Преподаватель выбрал ресурс, к которому планирует предоставить доступ учащемуся в курсе.
Учащийся открывает модуль "Библиотека ресурсов" с ресурсом, настроенным ранее преподавателем.
Система должна отобразить ресурс учащемуся.

​Возможны три режима отображения:

    - встроенный контент. Модуль "Библиотека ресурсов" отобразит учащемуся плеер. Формирование кода плеера производится либо по образцу от источника (в образец подставляются параметры ресурса), либо источник должен предоставить готовый html-код плеера по запросу. Получившийся код отображается в СДО как есть, соответственно необходимо обеспечить использование только полных ссылок в контенте.
    - транслированный контент. Модуль "Библиотека ресурсов" отображает html-код ресурса, предоставленный источником, предварительно заменяя оригинальные ссылки, ведущие на материалы источника (не внешние) содержащиеся в контенте ресурса, на ссылку до специального скрипта, выполняющего маршрутизацию. Скрипт маршрутизации принимает в качестве параметра ссылку до источника и выполняет запрос к источнику на получение контента, передавая токен авторизации. Это позволяет организовать учащимся в СДО доступ к закрытому контенту без публикации ключей авторизации. Доступ предоставляется только пользователям, имеющим доступ к соответствующему элементу курса (авторизованы, подписаны на курс, дошли до изучения ресурса).
    - ссылка со сквозной авторизацией. При переходе учащегося к ресурсу, модуль "Библиотека ресурсов" запрашивает у источника предавторизованную (содержащую токен авторизации) ссылку на ресурс по идентификатору ресурса. Минусом данного режима является переход на другой сайт и изменение внешнего вида системы.

​Пример запроса ресурса с комментариями по возможностям реализации:

ENDPOINT
    - /api/resource_content
HEADERS
    - token - токен авторизации
GET
    - id - идентификатор ресурса
    - user - данные, идентифицирующие пользователя (для статистики)
    - course - данные, идентифицирующие курс (для статистики)
    - module - данные, идентифицирующие элемент курса (для статистики)
    - session - данные, идентифицирующие сессию (для статистики)
ОТВЕТ
    В ответ приходит объект JSON, содержащий результат обработки запроса и данные о ресурсе:
    - (bool) success - результат обработки запроса
    - (string) error - описание ошибки (если результат обработки запроса не был успешным)
    - (string) content - либо html-код плеера, либо html-код ресурса (контент), либо предавторизованная ссылка (в зависимости от необходимого режима отображения)
    Ответ может также содержать другие данные, если выбран режим отображения, подразумевающий необходимость подставлять в образец кода плеера данные об отображаемом ресурсе.

​ДОПОЛНИТЕЛЬНАЯ ИНФОРМАЦИЯ

Источник может предоставить дополнительные файлы, необходимые html-плееру, например, скрипты javascript или стили css. Они могут быть переданы двумя способами:
- источник может вернуть предавторизованные ссылки (могут содержать дополнительные ключи прямо в URL, не должны требовать авторизации), которые модуль "Библиотека ресурсов" подставит в html-код.
- источник может предоставить API для запроса этих файлов. Модуль "Библиотека ресурсов" странслирует эти файлы. В этом случае, система проверит, что пользователь авторизован и имеет доступ к просмотру конкретного ресурса.

Рейтинг ответа: 0 (0 оценок)

Комментарии запрещены