Протокол «БиблиоКербер» v2

Определения, обозначения, сокращения

  • Сервис – сервис выдачи, владелец защищенных ресурсов.
  • Клиент – ПО просмотра документов.
  • Пользователь – конечный пользователь, получающий доступ к документам.

Общая информация

  • Взаимодействие с сервисом должно осуществляться по защищённому протоколу HTTPS.
  • В каждом запросе клиент должен передавать ключ доступа в заголовке X-APIKey.

Идентификация пользователей

Идентификация пользователей производится посредством передачи токена безопасности пользователя с каждым запросом к сервису с помощью заголовка Authorization. За идентификацию пользователя отвечает Клиент. Он проверяет учётные данные пользователя, получающего доступ к системе, и предоставляет Сервису информацию о пользователе в виде подписанного Клиентом JWT токена. Сервис полностью доверяет информации о пользователе, предоставленной Клиентом.

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

Название параметра Описание Обязательность
email Электронный адрес пользователя. Необязательный
fullName Полное имя пользователя. Необязательный
birthDate Дата рождения пользователя. Необязательный
userId Уникальный идентификатор пользователя в системе аутентификации. Обязательный
ip IP-адрес пользователя. Обязательный
authProvider Сервис аутентификации:
  • local – локальный логин/пароль
  • vkontakte – Вконтакте
  • facebook – Facebook
  • odnoklassniki – Одноклассники
  • gosuslugi – ГосУслуги
 Обязательный
roomId Уникальный идентификатор читального зала. Обязательный, если доступ осуществляется из читального зала.
room Название читального зала. Обязательный, если доступ осуществляется из читального зала.

Пример заголовка:

Authorization: Bearer eyJhbGciOiJIUzI1NiIXVCJ9...TJVA95OrM7E20RMHrHDcEfxjoYZgeFONFh7HgQ

Описание запросов

Получение разрешений пользователя на документ

Запрос позволяет получить разрешённые действия с документом. Если в запросе отсутствует JWT токен, то будет возвращен список разрешений для анонимного пользователя.

Запрос

GET /{id}/info/permissions

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

Ответ

Content-Type: application/json

Представляет собой массив объектов следующей структуры

Название параметра Описание
action Действие на документ. Возможные действия:
  • Open – открытие документа, поиск
  • Display – просмотр указанного набора страниц
  • Print – печать указанного набора страниц
  • Download – скачивание документа полностью
allowed Признак наличия разрешения на действие. Возможные значения:
  • true – действие разрешено
  • false – действие запрещено
pages Список номеров страниц, для которых разрешено действие. Формат списка страниц: 1-3,10,23-30.
Список страниц возвращается только для постраничных действий: display, print.

Пример ответа:

[
    {
        "action": "open",
        "allowed": "true"
    }, 
    {
        "action": "display",
        "allowed": "true",
        "pages": [1-3,10,23-30]
    }, 
    {
        "action": "print",
        "allowed": "true",
        "pages": [1-3]
    }
]

Открытие документа

Запрос необходим для учёта факта открытия документов.

Запрос

POST /{id}/open

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

Получение информации о количестве страниц документа

Запрос возвращает фактическое количество страниц документа.

Запрос

GET /{id}/info/pages_count

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

Ответ

Content-Type: application/json

Название параметра Описание
pages_count Количество страниц документа.

Пример ответа:

{"pages_count": 200}

Получение информации о защищённости документа авторским правом

Запрос возвращает признак защищённости авторским правом.

Запрос

GET /{id}/info/copyrights

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

Ответ

Content-Type: application/json

Название параметра Описание
is_copyrighted Признак защищённости авторским правом.

Пример ответа:

{"is_copyrighted": true }

Получение библиографического описания документа

Запрос возвращает библиографическое описание в формате MODS.

Запрос

GET /{id}/mods

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

Ответ

Content-Type: application/xml

Пример ответа:

<mods xmlns="http://www.loc.gov/mods/v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:msxsl="urn:schemas-microsoft-com:xslt" version="3.4">
  <titleInfo>
    <title>
Карта земли войска Донского, рисунки: воинской и домашней одежды донских казаков и регалий, всемилостивейше пожалованных войску Донскому
    </title>
    <subTitle>К Статистическому описанию Земли войска Донского</subTitle>
  </titleInfo>
  <originInfo>
    <dateIssued>[1883?]</dateIssued>
  </originInfo>
  <subject>
    <titleInfo>
      <title>История донского казачества коллекция</title>
    </titleInfo>
  </subject>
  <subject>
    <titleInfo>
      <title>Быт, обычаи, обряды на Дону коллекция</title>
    </titleInfo>
  </subject>
  <recordInfo>
    <recordCreationDate encoding="marc">111221</recordCreationDate>
    <recordChangeDate encoding="iso8601">20130829225433.2</recordChangeDate>
    <recordIdentifier>ROSTOV\BIBL\z0000314076</recordIdentifier>
  </recordInfo>
</mods>

Получение информации о размерах страниц документа

Запрос предназначен для получения физических размеров страниц документа. В параметрах запроса может быть указан перечень страниц, для которых запрашиваются размеры.

Запрос

GET /{id}/info/pages_sizes

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

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

Название параметра Описание
page_numbers Необязательный параметр. Список номеров страниц в формате 1-3,10,23-30.

Если параметр page_numbers не указан, запрос возвращает фактические размеры всех страниц документа.

Ответ

Content-Type: application/json

В ответе передаётся объект, у которого ключами являются номера страниц, а значениями объекты следующей структуры:

Название параметра Описание
w Ширина страницы в пунктах (PostScript point).
h Высота страницы в пунктах (PostScript point).

Пример ответа:

{"1": {"w": 300, "h": 450}, "2": {"w": 300, "h": 450}, …}

Получение текста документа

Запрос возвращает полный текст документа. В качестве разделителя страниц используется символ \0xC.

Запрос

GET /{id}/text

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

Ответ

Content-Type: text/plain

Загрузка документа

Возвращает поток байт PDF файла или ZIP файла, если документ состоит из нескольких файлов. Запрос поддерживает загрузку определённого диапазона байт с помощью HTTP Range.

Запрос

GET /{id}/download

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

Ответ

Content-Type: application/pdf либо application/zip

Получение изображения страницы документа

Запрос возвращает изображение страницы в формате JPEG. С помощью дополнительных параметров можно указать, в каком качестве и размере требуется изображение.

Запрос

GET /{id}/page/{page_number}/image

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.
page_number Номер страницы.

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

Название параметра Описание
purpose Назначение получаемого изображения страницы:
  • thumbnail — для отображения эскиза страницы
  • display — для отображения страницы на экране
  • print — для печати страницы
Данный параметр используется для фиксации в статистике.
dpi Необязательный параметр. Разрешение, точек на дюйм.
Максимальные значения для каждого назначения:
  • thumbnail — 72
  • display — 300
  • print — 300
Значение этого параметра определяет размер изображения, если не заданы width или height. Если width и height указаны, dpi не применяется.
height Необязательный параметр. Высота изображения страницы.
width Необязательный параметр. Ширина изображения страницы.
scale_method Необязательный параметр. Метод масштабирования изображения при одновременно указанных параметрах width и height:
  • fit — изображение вписывается целиком в прямоугольник указанных размеров
  • fill — изображение полностью заполняет прямоугольник указанных размеров без сохранения aspect ratio. Это значение по умолчанию.
Если один из параметров width или height не указан, scale_method не применяется.

Ответ

Content-Type: image/jpeg

Поиск по документу

Запрос предназначен для поиска заданного текста по всему документу. Возвращает текстовые отрывки и соответствующие номера страниц. Если искомый текстовый отрывок состоит из нескольких слов, запрос возвращает вхождения каждого из искомых слов.

Запрос

GET /{id}/search

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.

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

Название параметра Описание
query Искомый текст.

Ответ

Content-Type: application/json

Представляет собой массив объектов следующей структуры

Название параметра Описание
snippet Текстовый отрывок с искомым текстом.
page Номер страницы.

Искомый текст выделяется в найденном отрывке с помощью HTML тега <b>.

Пример ответа:

[{"snippet": "я помню <b>чудное</b> мгновенье", "page": 50}, …]

Поиск на странице

Запрос предназначен для поиска координат заданных слов на заданной странице. Отсчёт координат ведётся от левого верхнего угла, в пунктах (PostScript point).

Запрос

GET /{id}/page/{page_number}/search

Параметры пути

Название параметра Описание
id Уникальный идентификатор документа.
page_number Номер страницы.

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

Название параметра Описание
query Искомый текст.

Ответ

Content-Type: application/json

Представляет собой массив объектов следующей структуры

Название параметра Описание
x Координата по горизонтали.
y Координата по вертикали.
w Ширина.
h Высота.

Пример ответа:

[{"x": 300, "y": 450, "w": 40, "h": 10}, …]

Коды ответов

Статус Описание
200 Успешно.
401 При запросе не передана информация о текущем пользователе.
403 Ключ X-APIKey не передан в заголовке запроса.
403 Ключ X-APIKey, переданный в запросе, не верен.
403 Обращение к запрещённым страницам или действиям.
404 Указанный в запросе документ или пакет доступа отсутствует.
500 Неправильно сформирован запрос или отсутствуют обязательные параметры запроса.