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

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

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

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

  • Взаимодействие с сервисом должно осуществляться по защищённому протоколу 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

Название параметра Описание
effective Массив действующих разрешений пользователя на данный документ.
available Массив доступных платных пакетов доступа.

Описание структуры элемента массива effective:

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

Описание структуры элемента массива available:

Название параметра Описание
id Уникальный идентификатор пакета доступа.
description Описание пакета доступа.
price Стоимость пакета доступа.
currency Валюта стоимости пакета доступа.
is_paid Признак того, что пользователь купил данный пакет.
permissions Разрешения, которые предоставляет данный пакет. Структура элемента аналогична структуре массива effective.

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

{
  "effective": [
    {
      "action": "open"
    },
    {
      "action": "display",
      "pages": "[1 - 3, 10, 23 - 30]"
    },
    {
      "action": "print",
      "pages": "[1 - 3]"
    }
  ],
  "available": [
    {
      "id": "a2316ab9-d9de-4e90-8738-55f5a96cf5d2",
      "description": "Полный доступ на просмотр документа",
      "price": "100.50",
      "currency": "RUB",
      "is_paid": "true",
      "permissions": [
        {
          "action": "open"
        },
        {
          "action": "display",
          "pages": "[1 - 30]"
        }
      ]
    },
    {
      "id": "73fd6fb8-4135-44f1-b9cf-e7e5a37db8b7",
      "description ": "Полный доступ к документу",
      "price": "300",
      "currency": "RUB",
      "is_paid": "false",
      "permissions": [
        {
          "action": "open"
        },
        {
          "action": "download"
        },
        {
          "action": "display",
          "pages": "[1 - 30]"
        }
      ]
    }
  ]
}

Получение ссылки на страницу оплаты

Запрос предназначен для получения ссылки на страницу оплаты пакета доступа в случае, когда пользователь производит оплату на стороне Сервиса. При оплате пакета доступа на стороне Клиента (см. запрос Информирование Сервиса об оплате) данный метод не вызывается.

Запрос

GET /{id}/permissions/available/{package_id}/payment_link

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

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

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

Название параметра Описание
success_url Необязательный параметр. URL, на который будет перенаправлен пользователь после успешной оплаты пакета доступа.
fail_url Необязательный параметр. URL, на который будет перенаправлен пользователь в случае неуспешной оплаты пакета доступа.

Ответ

Content-Type: application/json

Название параметра Описание
link Ссылка на страницу оплаты пакета доступа.

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

{"link": "https://example.org/..."}

Информирование Сервиса об оплате на стороне Клиента

Запрос предназначен для информирования Сервиса о факте успешной оплаты пакета доступа Пользователем на стороне Клиента. После вызова этого метода Сервис отмечает пакет доступа как приобретённый и при последующих ответах на запрос permissions возвращает для данного пакета доступаis_paid="true", а права, предоставляемые оплаченным пакетом доступа, включены в массив effective.

В случае оплаты на стороне Сервиса (см. запрос Получение ссылки на страницу оплаты) данный метод не вызывается.

Запрос

POST /{id}/permissions/available/{package_id}/purchase

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

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

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

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

Запрос

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 Неправильно сформирован запрос или отсутствуют обязательные параметры запроса.