LMS adabiyot API

Universitet LMS'i fanlar uchun adabiyotlarni elib katalogidan oladi

Umumiy

Fanlar LMS'da yaratiladi. O'qituvchi fanga adabiyot biriktirganda LMS shu API orqali elib katalogidan qidiradi va tanlangan kitoblarning ID'sini (Koha biblionumber) o'zida saqlaydi. Talabaga fan sahifasida adabiyotlar ro'yxati ko'rsatiladi: ma'lumotlar shu ID'lar bo'yicha elib'dan olinadi, "O'qish" havolasi esa talabani LMS orqali elib'ga kiritib, kitobni ochadi.

Asosiy manzil: https://elib.npuu.uz/api/lms/v1
Format: JSON (UTF-8), faqat GET so'rovlar
OpenAPI 3 spetsifikatsiyasi: https://elib.npuu.uz/developers/lms/openapi.json
Kitoblar Koha'dan jonli olinadi: elib ularni o'z bazasida saqlamaydi.
Katalogda LMS a'zolari uchun belgilangan ko'rinish qoidalari amal qiladi (yashirin turlar qaytmaydi).

Kirish (API kalit)

Kalitni elib administratori admin panelning "LMS va API" sahifasidagi "Adabiyot API kalitlari" bo'limida yaratadi. Kalit faqat yaratilganda bir marta ko'rsatiladi: uni LMS serverida maxfiy saqlang (brauzerga yubormang). Har so'rovda sarlavhada yuboriladi:

Authorization: Bearer elib_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Kalit yo'q yoki bekor qilingan bo'lsa: 401. Chegara: bitta IP manzildan (LMS serveridan) daqiqasiga 600 so'rov. Oshsa 429 qaytadi, Retry-After sarlavhasi necha soniyadan keyin qayta urinish mumkinligini aytadi.

So'rovlar

`GET /books`: katalogdan qidirish

O'qituvchi adabiyot tanlaydigan oyna uchun.

q: qidiruv matni (nomi, muallif, mavzu va boshqa maydonlar bo'yicha); author: faqat muallif bo'yicha
type: material turi kodi, masalan KITOB (/item-types); language: til kodi, masalan uzb (/languages)
page (1 dan), per_page (1–50, standart 20)
Tartib: q berilsa eng mos kitoblar birinchi keladi, berilmasa katalogga oxirgi qo'shilganlar.

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'lar bo'yicha

Fan sahifasida adabiyotlar ro'yxatini chiqarish uchun: 50 tagacha ID, javob shu tartibda. ids berilsa boshqa parametrlar hisobga olinmaydi. Topilmagan yoki yashirilgan ID'lar meta.missing da qaytadi.

meta.missing da faqat Koha'da yo'q yoki LMS uchun yashirilgan kitoblar bo'ladi. Ularni avtomatik o'chirmasdan o'qituvchiga ko'rsating: kutubxona yashirishni keyin bekor qilishi mumkin.

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

`GET /books/{id}`: to'liq ma'lumot

Qo'shimcha maydonlar: subtitle, contributors, publisher, place, edition, series, pages, language, udc, subjects, keywords, description. Topilmasa: 404.

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

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

Qidiruv filtrlari uchun ro'yxatlar. Material turlari Koha'dagi ro'yxatdan olinadi va kutubxona yangi tur qo'shsa o'zgaradi, shuning uchun kodlarni shu so'rovdan oling.

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

Javob namunasi

{
    "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: kutubxonadagi bosma nusxalar, jami va hozir berish mumkin bo'lganlari.
ebook.available: kitobning PDF'i elib o'quvchisida ochiladi; ebook.paid va ebook.price: LMS orqali kirgan talaba bu kitob uchun to'laydimi va qancha. Kutubxona kitobni LMS a'zolari uchun bepul qilgan bo'lsa, ebook.paid false bo'ladi.
cover_url: elib'dagi muqova rasmi, kichik o'lchamda (/covers/{id}/thumb). Muqovasi yo'q kitoblarda null.
links.page: kitobning elib sahifasi (bron qilish shu yerda).
links.read: talaba bosganda LMS orqali avtomatik kiradi va kitob o'quvchisi ochiladi; elib'ga allaqachon kirgan talaba LMS'ga qayta yuborilmaydi. PDF bo'lmasa null.

Xatolar

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

401 unauthorized
404 not_found
422 parametr noto'g'ri (Laravel formati: message va errors)
429 chegaradan oshdi (Laravel formati: message, Retry-After sarlavhasi bilan)
503 unavailable: katalog vaqtincha javob bermayapti, Retry-After sarlavhasidagi soniyadan keyin qayta so'rang

Koha vaqtincha javob bermasa /books va /item-types so'rovlari 503 qaytaradi va qisman ro'yxat bermaydi. Bunda LMS'dagi ro'yxatni o'zgartirmang: oxirgi saqlangan ma'lumotni ko'rsating va keyinroq qayta so'rang.

Tavsiya etilgan integratsiya

LMS'da fan uchun course_literature (course_id, elib_book_id, kind) kabi jadval yuriting; kind: asosiy yoki qo'shimcha.
O'qituvchining tanlash oynasida /books?q=… natijalarini ko'rsating va tanlangan id'ni saqlang.
Talaba sahifasida /books?ids=… bilan ma'lumotlarni oling va 10–30 daqiqa keshlang (elib ham 10 daqiqa keshlaydi).
"O'qish" tugmasiga links.read, "Batafsil" ga links.page qo'ying.
503 kelsa ro'yxatga tegmang va keshdagi ma'lumotni ko'rsating; meta.missing dagi kitoblarni o'qituvchiga "topilmadi" deb belgilang.