API литературы для LMS

LMS университета получает литературу для дисциплин из каталога elib

Общее

Дисциплины создаются в LMS. Когда преподаватель прикрепляет литературу к дисциплине, LMS ищет её в каталоге elib через этот API и сохраняет ID выбранных книг (biblionumber в Koha). Студенту на странице дисциплины показывается список литературы: данные берутся из elib по этим ID, а ссылка «Читать» входит в elib через LMS и открывает книгу.

Базовый адрес: https://elib.npuu.uz/api/lms/v1
Формат: JSON (UTF-8), только запросы GET
Спецификация OpenAPI 3: https://elib.npuu.uz/developers/lms/openapi.json
Книги берутся из Koha в реальном времени: elib не хранит их в своей базе.
Действуют правила видимости каталога для пользователей LMS (скрытые типы не возвращаются).

Доступ (API-ключ)

Ключ создаёт администратор elib в админ-панели на странице «LMS и API», в разделе «Ключи API литературы». Ключ показывается один раз при создании: храните его в секрете на сервере LMS (не передавайте в браузер). Он передаётся в заголовке каждого запроса:

Authorization: Bearer elib_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Если ключа нет или он отозван: 401. Лимит: 600 запросов в минуту с одного IP-адреса (сервера LMS). При превышении возвращается 429, а заголовок Retry-After сообщает, через сколько секунд можно повторить запрос.

Запросы

`GET /books`: поиск по каталогу

Для окна, в котором преподаватель выбирает литературу.

q: текст поиска (по названию, автору, теме и другим полям); author: только по автору
type: код типа материала, например KITOB (/item-types); language: код языка, например uzb (/languages)
page (с 1), per_page (1–50, по умолчанию 20)
Порядок: с q сначала идут самые подходящие книги, без него — последние добавленные в каталог.

curl -H "Authorization: Bearer $ELIB_KEY" "https://elib.npuu.uz/api/lms/v1/books?q=pedagogika&per_page=20"

`GET /books?ids=54410,52047`: по ID

Для вывода списка литературы на странице дисциплины: до 50 ID, ответ в том же порядке. Если передан ids, остальные параметры не учитываются. Ненайденные или скрытые ID возвращаются в meta.missing.

В meta.missing попадают только книги, которых нет в Koha или которые скрыты для пользователей LMS. Не удаляйте их автоматически, покажите преподавателю: библиотека может позже снять скрытие.

curl -H "Authorization: Bearer $ELIB_KEY" "https://elib.npuu.uz/api/lms/v1/books?ids=54410,52047,60787"

`GET /books/{id}`: полные сведения

Дополнительные поля: subtitle, contributors, publisher, place, edition, series, pages, language, udc, subjects, keywords, description. Если не найдено: 404.

curl -H "Authorization: Bearer $ELIB_KEY" "https://elib.npuu.uz/api/lms/v1/books/54410"

`GET /item-types`, `GET /languages`

Списки для фильтров поиска. Типы материалов берутся из списка в Koha и меняются, когда библиотека добавляет новый тип, поэтому берите коды из этого запроса.

{"data": [{"code": "KITOB", "name": "Kitob"}, {"code": "DISS", "name": "Dissertatsiya va avtoreferat"}, …]}
{"data": [{"code": "uzb", "name": "O'zbek"}, {"code": "rus", "name": "Rus"}, {"code": "eng", "name": "Ingliz"}, …]}

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

{
    "data": [
        {
            "id": 54410,
            "title": "Umumiy pedagogika (pedagogika nazariyasi)",
            "author": "Abdullayeva B. S.",
            "year": 2022,
            "isbn": "9789943646551",
            "item_types": [
                "KITOB"
            ],
            "cover_url": null,
            "copies": {
                "total": 1,
                "available": 1
            },
            "ebook": {
                "available": true,
                "paid": false,
                "price": null,
                "access_days": null
            },
            "links": {
                "page": "https://elib.npuu.uz/books/54410",
                "read": "https://elib.npuu.uz/auth/lms?redirect=%2Fread%2F54410"
            }
        }
    ],
    "meta": {
        "page": 1,
        "per_page": 20,
        "total": 1318,
        "total_pages": 66
    }
}

copies: печатные экземпляры в библиотеке, всего и доступные к выдаче сейчас.
ebook.available: PDF книги открывается в читалке elib; ebook.paid и ebook.price: платит ли студент, вошедший через LMS, за эту книгу и сколько. Если библиотека сделала книгу бесплатной для пользователей LMS, ebook.paid будет false.
cover_url: обложка на elib в маленьком размере (/covers/{id}/thumb). У книг без обложки: null.
links.page: страница книги в elib (там же бронирование).
links.read: по нажатию студент автоматически входит через LMS и открывается читалка; студент, уже вошедший в elib, повторно в LMS не перенаправляется. Если PDF нет: null.

Ошибки

{"error": {"code": "not_found", "message": "Kitob topilmadi"}}

401 unauthorized
404 not_found
422 неверный параметр (формат Laravel: message и errors)
429 превышен лимит (формат Laravel: message, с заголовком Retry-After)
503 unavailable: каталог временно не отвечает, повторите запрос через число секунд из заголовка Retry-After

Если Koha временно не отвечает, запросы /books и /item-types возвращают 503 и не отдают неполный список. В этом случае не меняйте список в LMS: показывайте последние сохранённые данные и повторите запрос позже.

API литературы для LMS

Общее

Доступ (API-ключ)

Запросы

GET /books: поиск по каталогу

GET /books?ids=54410,52047: по ID

GET /books/{id}: полные сведения