LMS literature API

The university LMS takes course literature from the elib catalogue

Overview

Courses are created in the LMS. When a teacher attaches literature to a course, the LMS searches the elib catalogue through this API and stores the IDs of the chosen books (the Koha biblionumber). Students see the reading list on the course page: the data comes from elib by those IDs, and the "Read" link signs the student in to elib through the LMS and opens the book.

Base URL: https://elib.npuu.uz/api/lms/v1
Format: JSON (UTF-8), GET requests only
OpenAPI 3 specification: https://elib.npuu.uz/developers/lms/openapi.json
Books are read live from Koha: elib does not store them in its own database.
The catalogue visibility rules set for LMS members apply (hidden types are not returned).

Access (API key)

An elib administrator creates the key in the admin panel on the "LMS va API" page, under "Adabiyot API kalitlari" (literature API keys). The key is shown only once, when it is created: keep it secret on the LMS server (never send it to a browser). Send it in a header with every request:

Authorization: Bearer elib_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A missing or revoked key returns 401. The limit is 600 requests per minute from one IP address (the LMS server). Above that you get 429, and the Retry-After header says how many seconds to wait before trying again.

Requests

`GET /books`: search the catalogue

For the window where a teacher picks literature.

q: search text (title, author, subject and other fields); author: author only
type: item type code, e.g. KITOB (/item-types); language: language code, e.g. uzb (/languages)
page (from 1), per_page (1–50, default 20)
Order: with q the best matches come first; without it, the books most recently added to the catalogue.

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

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

For showing a course reading list: up to 50 IDs, answered in the same order. When ids is given, the other parameters are ignored. IDs that weren't found or are hidden come back in meta.missing.

meta.missing holds only books that Koha doesn't have or that are hidden from LMS members. Don't delete them automatically; show them to the teacher, since the library may unhide them later.

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

`GET /books/{id}`: full record

Extra fields: subtitle, contributors, publisher, place, edition, series, pages, language, udc, subjects, keywords, description. Not found: 404.

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

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

Lists for search filters. Item types come from Koha's list and change when the library adds a new type, so take the codes from this request.

{"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"}, …]}

Sample response

{
    "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: printed copies in the library, in total and available to borrow now.
ebook.available: the book's PDF opens in the elib reader; ebook.paid and ebook.price: whether a student signed in through the LMS pays for this book, and how much. When the library has made the book free for LMS members, ebook.paid is false.
cover_url: the cover image on elib, small size (/covers/{id}/thumb). null for books without a cover.
links.page: the book's page on elib (holds are placed there).
links.read: when a student clicks it, they are signed in through the LMS and the book reader opens; a student already signed in to elib is not sent to the LMS again. null when there is no PDF.

Errors

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

401 unauthorized
404 not_found
422 invalid parameter (Laravel format: message and errors)
429 rate limit exceeded (Laravel format: message, with a Retry-After header)
503 unavailable: the catalogue is briefly not answering; try again after the number of seconds in the Retry-After header

When Koha is briefly unavailable, /books and /item-types requests return 503 and never a partial list. Leave the list in the LMS as it is: show the last saved data and ask again later.

Recommended integration

Keep a table such as course_literature (course_id, elib_book_id, kind) in the LMS; kind: core or supplementary.
In the teacher's picker, show the /books?q=… results and store the chosen id.
On the student page, fetch the data with /books?ids=… and cache it for 10–30 minutes (elib also caches for 10 minutes).
Point the "Read" button at links.read and "Details" at links.page.
On 503 leave the list alone and show the cached data; mark books in meta.missing as "not found" for the teacher.