Dokumentacija spletnega API-ja digitalne knjižnice

Preko naslova ajax.php je dosegljiv spletni API digitalne knjižnice (DK), ki omogoča AJAX operacije za lastne potrebe ali za potrebe tretjih aplikacij. V nadaljevanju so opisani ukazi, ki jih API omogoča.

Za proženje ukaza je potrebno najprej posredovati parameter cmd. Parameter se posreduje po metodi POST ali GET, kar je odvisno od ukaza in je omenjeno pri vsakem ukazu posebej.

Poleg naziva ukaza se nahajajo značke z dodatnimi informacijami:


Seznam ukazov:

doAjaxTest
getAdvancedSearch
getBrowse
getCsl
getDoc
getDocument
getGradivoID
getIP
getOpis
getSearch
urlAsQr

doAjaxTest

POST

Omogoča testiranje AJAX klicev na različne načine. Deluje tudi preko metode GET.

Vhod:

Parameter Opis
value Poljuben vhodni parameter. Podatek se vrne na izhodu.
mode Način delovanja AJAX zahtevka. Možno so:
  • json - sproži navaden HTTP zahtevek. Je privzeta vrednost in velja tudi v primeru, da ne zadostimo pogojem drugih načinov.
  • jsonp - sproži JSONP zahtevek, ki omogoča klic iz druge domene. Na vhodu pričakuje GET parameter "callback" (kot uporabljeno v jQuery). Če parameter ni na voljo, se izvede zahtevek po načinu "json".
  • cors - sproži navaden HTTP zahtevek, ki omogoča klic iz druge domene s pomočjo "Cross Origin Resource Sharing". Nekateri starejši brskalniki tega ne podpirajo.
callback Parameter, potreben samo v načinu "jsonp".

Izhod:

Vrne JSON/JSONP zapis z vrednostima "value" in "mode". Slednji se lahko razlikuje, če pogoji za "mode" niso bili doseženi, npr. pri načinu "jsonp" ni GET parametra "callback".

Primer navadnega AJAX klica.
Primer AJAX klica po metodi CORS, ki v HTTP glavi odgovora vrne "Access-Control-Allow-Origin: *", ki brskalniku dovoli klic iz druge domene.

V zvezi s tem je bila napisana datoteka HTML, ki izvede klic na vse tri načine in se lahko koristi za preverjanje podpore brskalnikov za različne načine AJAX klicev.

Na vrh

getAdvancedSearch

GET

Vrne vse podatke za izvedbo naprednega iskanja za potrebe mobilnih naprav in zunanjih aplikacij. Iskanje na vhodu prejme do štiri iskalne nize pri štirih kriterijih in operatorjih iskanja in dodatne filtre. Zadetke vrača v obliki seznama zadetkov, ki je razdeljen na strani.

Vhod:

Parameter Opis
lang ISO639-3 koda jezika, v katerem je uporabniški vmesnik. Podprti so samo jeziki, v katerih je dosegljiv digitalni repozitorij, običajno slovenščina (slv) in angleščina (eng). Privzeto "slv".
val1 - val4 Vrednost oz. iskalni niz iskalnega kriterija. Pošljejo se lahko največ štirje iskalni niz, ki se jih označi s številko od 1 do 4 na koncu parametera. Iskalni nizi imajo tudi operator (op1) in stolpec iskanja (col1), ki se jih označi podobno.
op1 - op4 Operator iskalnega kriterija pripadajočega iskalnega niza.
col1 - col4 Stolpec iskanja pripadajočega iskalnega niza.
source ID organizacije, katerih gradiva naj vrača. Privzeto prazen niz, kar preskoči izvedbo iskanja. Za izvedbo iskanja je ta podatek obvezen. Če parameter ni podan, se iskanje ne izvede, vrne pa podatke za izpis vnosne forme.
workType Vrsta gradiva (diplome, magisteriji, doktorati...) Privzeto prazen niz, vrsta gradiva ni kriterij pri iskanju (vrača vse vrste gradiv).
language Jezik gradiva. Privzeto prazen niz, jezik ni kriterij pri iskanju (vrača se gradiva vseh jezikov). Ta parameter ni povezan s podatkom "lang".
fullTextOnly Ali naj vrača samo zadetke z datoteko.
page Zaporedna številka izpisane strani zadetkov. Privzeto 1 (prva stran).
pageSize Število prikazanih gradiv na stran. Privzeto 10.
callBack Ime funkcije za potrebe JSONP. Privzeto prazen niz, funkcija vrne navaden JSON.

Izhod:

Vrne JSON ali JSONP z vsemi podatki za prikaz vnosne forme iskalnika in iskalnih zadetkov. V primeru napake vrne prazen niz ali vsebino, ki ni JSON. Polna shema je naslednja:

Parameter Tip Opis
queryType string Niz "napredno".
query polje Podatki za izpis posameznega iskalnega kriterija, ki je del vnosne forme iskalnika. Posamezni iskalni kriterij ima svojo shemo, ki je opisana tukaj.
    source iskalni kriterij Organizacije gradiva.
    fullTextOnly iskalni kriterij Ali naj vrača samo dela z datoteko ali vsa dela.
    language iskalni kriterij Določa jezik iskanih gradiv.
    workType iskalni kriterij Določa vrsto gradiva.
    string1 iskalni kriterij Prvi iskalni niz z operatorjem in stolpcem iskanja.
    string2 iskalni kriterij Drugi iskalni niz.
    string3 iskalni kriterij Tretji iskalni niz.
    string4 iskalni kriterij Četrti iskalni niz.
results polje Polje iskalnih zadetkov, če iskanje izvedeno. Shema je enaka kot pri enostavnem iskanju in je opisana tukaj.
pagingInfo polje Podatki o straničenju zadetkov iskanja. Podatek je na voljo le, če je hkrati na voljo tudi podatek "results". Shema je enaka kot pri enostavnem iskanju in je opisana tukaj.
redirect URL V primeru, da gre za iskanje po COBISS virih, se to iskanje izvede na COBISS-u. Za ta namen se vrne URL, na katerega preusmerimo uporabnika.
message string V določenih primerih lahko pride do napake uporabnika, kar ga opozorimo z obvestilom. V tem primeru tukaj prejmemo kodo obvestila. Kode so lahko naslednje:
  • cobiss_vpisiNiz - pri iskanju po COBISS je vnos iskalnega niza obvezen;
  • cobiss_izberiVir - iskanje po opciji "COBISS" ni mogoče, uporabnik naj izbere enega izmed virov COBISS.

Primer izhodnih podatkov, kjer se iskanje ne izvede. S tem dobimo podatke za izpis obrazca naprednega iskanja, saj dobimo nabor dovoljenih vrednosti operatorjev in stolpcev iskanja ter nekaterih filtrov.
Primer iskanja po nizu "celica" po naslovu (privzeto) in vseh organizacijah, ostale vrednosti so privzete.

Na vrh

getBrowse

GET

Vrne vse podatke za brskanje za potrebe mobilnih naprav in zunanjih aplikacij. Brskanje se izvaja s pomočjo različnih kategorij metapodatkov, kjer uporabnik izbira kategorije v več nivojih. Določene kombinacije izbranih karegorij vračajo gradiva v obliki seznama, ki je izpisan po straneh.

Vhod:

Parameter Opis
lang ISO639-3 koda jezika, v katerem je uporabniški vmesnik. Podprti so samo jeziki, v katerih je dosegljiv digitalni repozitorij, običajno slovenščina (slv) in angleščina (eng). Privzeto "slv".
cat1 ID izbrane vrednosti kategorije na prvem nivoju. Privzeto prazen niz, kar pomeni, da nobena vrednost ni izbrana.
cat2 ID izbrane vrednosti kategorije na drugem nivoju. Privzeto prazen niz, kar pomeni, da nobena vrednost ni izbrana.
cat3 ID izbrane vrednosti kategorije na tretjem nivoju. Privzeto prazen niz, kar pomeni, da nobena vrednost ni izbrana.
page Zaporedna številka izpisane strani zadetkov. Privzeto 1 (prva stran).
pageSize Število prikazanih gradiv na stran. Privzeto 10.
callBack Ime funkcije za potrebe JSONP. Privzeto prazen niz, funkcija vrne navaden JSON.

Izhod:

Vrne JSON ali JSONP z vsemi podatki za prikaz strani brskanja gradiv po kategorijah. V primeru napake vrne prazen niz ali vsebino, ki ni JSON. Polna shema je naslednja:

Parameter Tip Opis
cat1 polje Seznam vrednosti prve kategorije. Vsak element polja vsebuje novo polje dveh vrednosti, kjer je prva vrednost ID vrednosti, druga vrednost je naziv vrednosti v izbranem jeziku.
cat2 polje Seznam vrednosti druge kategorije, če je podan vhodni parameter cat1, sicer ta podatek ni na voljo. Struktura je enaka kot pri cat1.
cat3 polje Seznam vrednosti tretje kategorije, če je podan vhodni parameter cat2, sicer ta podatek ni na voljo. Struktura je enaka kot pri cat1.
results polje Seznam gradiv trenutno prikazane strani. Shema posameznega gradiva zajema del metapodatkov, primeren za izpis zadetka brskanja. Podatki so na voljo le, če so izbrane ustrezne kategorije, sicer podatka ni. Shema je enaka kot pri enostavnem iskanju in je opisana tukaj.
pagingInfo polje Podatki o straničenju zadetkov brskanja. Podatek je na voljo le, če je hkrati na voljo tudi podatek "results". Shema podatka je enaka kot pri enostavnem iskanju in je opisana tukaj.

Primer izhodnih podatkov, ko na vhodnu podamo minimalno podatkov.
Primer z izbranimi kategorijami, ki vračajo gradiva.

Na vrh

getCsl

GET

Sestavi citat podanega gradiva v podanem formatu in vrne vsebino kot datoteko. CSL je kratica za "Citation Style Language".

Vhod:

Parameter Opis
gID ID gradiva, katerega citatne podatke želimo.
lang ISO639-3 koda jezika, v katerem naj bodo oznake metapodatkov. Privzeto "slv". Npr. to funkcijo se kliče pri izpisu gradiva, pri tem se kot jezik pošlje trenutno nastavljen jezik spletne strani.
format Željen format citatnih podatkov. Možni so naslednji formati:
  • ris - Research Information System
  • refer - EndNote/Refer
  • endnotexml - EndNote XML
  • txt - golo besedilo

Izhod:

Izhod so citatni podatki za podano gradivo v podanem formatu v obliki datoteke (sproži se prenos datoteke). V primeru napake ali če gradivo ne obstaja, se vrne prazen niz.

Na vrh

getDoc

GET  servisAuth

Vrne predstavitveno datoteko podanega gradiva ali točno določeno datoteko. Storitev deluje tudi, če prijavni ključ ni naveden, a je na tak način mogoče dobiti samo javno dosegljive datoteke. Dostopi brez prijavnega ključa se v statistika dostopa štejejo kot prenosi (npr. prenos za potrebe mobilnih aplikacij).

Vhod:

Parameter Opis
hash Prijavni ključ odjemalca. Če ključ ni naveden, se lahko dostopa do javno dosegljvih datotek. Odjemalcu se lahko v RUL doda naslednje pravice:
  • getDoc_AllowDataDump - možnost prenosa posebne ZIP datoteke s šifranti (za trajno hranjenje)
  • getDoc_AllowDeleted - možnost prenosa datotek, označenih kot zbrisane (za trajno hranjenje)
gID ID gradiva, katerega datoteko predstavitveno datoteko želimo.
dID ID datoteke, ki jo želimo. Parameter se ignorira, če podan gID.

Izhod:

Vrne datoteko s pravim MIME tipom ali kodo napake ali opis napake.

Na vrh

getDocument

GET

Vrne polni nabor metapodatkov gradiva.

Vhod:

Parameter Opis
gID ID zahtevanega gradiva
lang SO639-3 koda jezika, v katerem je uporabniški vmesnik. Podprti so samo jeziki, v katerih je dosegljiv digitalni repozitorij, običajno slovenščina (slv) in angleščina (eng). Privzeto "slv".
callBack Ime funkcije za potrebe JSONP. Privzeto prazen niz, funkcija vrne navaden JSON.
version Verzija, ki določa nabor in strukturo izhodnih podatkov:
  • 1 - privzeta vrednost, vrača prvotni nabor podatkov gradiva;
  • 2 - vsi podatki prejšnje verzije, a je projektov lahko več (ne samo en), izpisani so vsi podatki posameznega projekta (ne samo ID projekta).

Izhod:

Vrne polni nabor metapodatkov gradiva v JSON ali JSONP obliki. Vrstni red oseb v polju "Osebe" je pomemben (določen s strani vnašalca). Nabor in struktura podatkov sta odvisna od zahtevane verzije izpisa.

Primer

Na vrh

getGradivoID

GET

Vrne ID gradiva glede na podan vhodni parameter. Na vhodu lahko podamo enega izmed naslednjih parametrov:

Vhod:

Parameter Opis
nrID ID dela v nacionalnem repozitoriju.
cobissID Cobiss ID dela.
dID ID datoteke, katere ID gradiva želimo.

Če podamo več vhodnih podatkov, se upošteva prvi podan.

Izhod:

ID gradiva ali 0, če zapis ne obstaja. Če vhod ni podan, vrne niz "NiVhodnegaPodatka".

Vsi spodaj navedeni primeri na vhodu pošljejo vrednost 123, kar zelo verjetno vrne vrednost 0. Vnesite ustrezno vrednost za delujoč primer.

Primer klica po ID-ju nacionalnega repozitorija
Primer klica po Cobiss ID
Primer klica po datoteki

Na vrh

getIP

GET

Vrne IP odjemalca. Mišljeno kot testna metoda. Nima vhodnih podatkov

Vhod:

Ni vhodnih podatkov.

Izhod:

IP odjemalca.

Primer

Na vrh

getOpis

GET

Vrne opis gradiva.

Vhod:

Parameter Opis
gID ID gradiva.

Izhod:

Golo besedilo opisa.

Na vrh

getSearch

GET

Vrne vse podatke za izvedbo enostavnega iskanja za potrebe mobilnih naprav in zunanjih aplikacij. Iskanje na vhodu poleg iskalnega niza lahko prejme nekaj preprostih filtrov. Zadetke vrača v obliki seznama zadetkov, ki je razdeljen na strani.

Vhod:

Parameter Opis
lang ISO639-3 koda jezika, v katerem je uporabniški vmesnik. Podprti so samo jeziki, v katerih je dosegljiv digitalni repozitorij, običajno slovenščina (slv) in angleščina (eng). Privzeto "slv".
query Iskalni niz. Privzeto prazen niz, kar vrne 100 zadnje objavljenih gradiv.
source ID organizacije, katerih gradiva naj vrača. Privzeto prazen niz, kar preskoči izvedbo iskanja. Za izvedbo iskanja je ta podatek obvezen. Če parameter ni podan, se iskanje ne izvede, vrne pa podatke za izpis vnosne forme.
fullTextOnly Ali naj vrača samo zadetke z datoteko.
page Zaporedna številka izpisane strani zadetkov. Privzeto 1 (prva stran).
pageSize Število prikazanih gradiv na stran. Privzeto 10.
callBack Ime funkcije za potrebe JSONP. Privzeto prazen niz, funkcija vrne navaden JSON.

Izhod:

Vrne JSON ali JSONP z vsemi podatki za prikaz vnosne forme iskalnika in iskalnih zadetkov. V primeru napake vrne prazen niz ali vsebino, ki ni JSON. Polna shema je naslednja:

Parameter Tip Opis
queryType string Niz "enostavno".
query polje Podatki za izpis posameznega iskalnega kriterija, ki je del vnosne forme iskalnika. Posamezni iskalni kriterij ima svojo shemo, ki je opisana tukaj.
    source iskalni kriterij Organizacije gradiva.
    fullTextOnly iskalni kriterij Ali naj vrača samo dela z datoteko ali vsa dela.
    string iskalni kriterij Iskalni niz.
results polje Polje iskalnih zadetkov, če iskanje izvedeno. Shema teh je opisana spodaj.
pagingInfo polje Podatki o straničenju zadetkov iskanja. Podatek je na voljo le, če je hkrati na voljo tudi podatek "dela".
redirect URL V primeru, da gre za iskanje po COBISS virih, se to iskanje izvede na COBISS-u. Za ta namen se vrne URL, na katerega preusmerimo uporabnika.
message string V določenih primerih lahko pride do napake uporabnika, kar ga opozorimo z obvestilom. V tem primeru tukaj prejmemo kodo obvestila. Kode so lahko naslednje:
  • cobiss_vpisiNiz - pri iskanju po COBISS je vnos iskalnega niza obvezen;
  • cobiss_izberiVir - iskanje po opciji "COBISS" ni mogoče, uporabnik naj izbere enega izmed virov COBISS.

Shema posameznega iskalnega kriterija je naslednja:

Parameter Tip Opis
operator string Iskalni operator. V primeru enostavnega iskanja je ta vedno in (and).
name string Naziv iskalnega kriterija.
value mixed Vrednost iskalnega kriterija (string ali int). Gre za vrednost z vhoda ali privzeta vrednost.
selItem string Izbran ID padajočega seznama iskalnega kriterija, če iskalni kriterij tak seznam ima. Npr. ID izbrane organizacije.
listItems polje Seznam vrednosti padajočega seznama. Vsak element seznama je novo polje dveh vrednosti, kjer je prva vrednost ID vrednosti, druga vrednost pa naziv vrednosti v zahtevanem jeziku.

Shema posameznega iskalnega zadetka ne zajema vseh podatkov gradiva, ampak samo podatke za izpis kot iskalni zadetek. Shema je naslednja:

Parameter Tip Opis
ID int ID gradiva v RUL.
Naslov string Naslov gradiva.
Osebe polje Seznam avtorjev dela (samo avtorjev).
    Ime string Ime osebe.
    Priimek string Priimek osebe.
LetoIzida int Leto izida gradiva.
KljucneBesede polje Seznam ključnih besed.
DatumObjave date Datum objave gradiva, format je razviden iz primera "2008-06-03 12:56:48".
StOgledov int Število ogledov gradiva.
StPrenosov int Število prenosov datotek gradiva.
VsotaOcen int Vsota vseh ocen uporabnikov, kjer uporabniki lahko dajo oceno od 0 do 5.
StOcen int Število ocen uporabnikov.
Organizacija polje Podatki o organizaciji.
    Naziv string Polno ime organizacije, pod katero gradivo spada.
    Logo string Ime datoteke logotipa organizacije. Ime ne vsebuje polne poti.
    LogoPolniUrl url Polni URL logotipa organizacije.
IzpisPolniUrl url Polni URL naslov za izpis gradiva.
StDatotek int Število vseh datotek tega gradiva.
Datoteke polje Polje datotek, a se vrne samo prvo predstavitveno datoteko. Zapis datoteka ima svojo shemo, opisano v naslednjih vrsticah:
    ID int ID prve predstavitvene datoteke tega gradiva. Lahko 0, če gradivo nima datotek.
    IkonaFormata string Ime datoteke z logotipom formata datoteke. Ime ne vsebuje polne poti datoteke.
    IkonaFormataPolniUrl url Polni URL logotipa formata.
    FormatDatoteke string Končnica datoteke, npr ".pdf".
    Url url URL datoteke, če datoteka ni iz RUL oz. prazen niz, če je.
    Naziv string Ime datoteke, če je datoteka iz RUL oz. prazen niz, če ni.
    PrenosPolniUrl url Polni URL za prenos datoteke v primeru, da je datoteka v RUL. Ta URL ne sproži prenosa, ampak najprej izpiše pogoje uporabe.
    VelikostDatoteke int Velikost datoteke v bajtih.
    VelikostDatotekeKratko string Velikost datoteke z smiselno predpono (npr. MB, KB).
    Namen string Namen datoteke (zmanjšan nabor), ki je lahko "Pred" za predstavitveno, "Raz" za raziskovalne podatke in "Ostalo" za ostalo.

Shema podatkov o straničenju je naslednja:

Parameter Tip Opis
numberOfRecords int Število vseh gradiv pri podanih kriterijih.
numberOfPages int Število strani, v katere so zapisi razporejeni.
pageSize int Število gradiv na stran. Vrednost je enaka vhodnemu parametru "pageSize".
currentPage int Številka trenutno izpisane strani zadetkov brskanja. Vrednost je enaka vhodnemu parametru "page".
startRecord int Zaporedna številka prvega zapisa na trenutno izpisani strani zadetkov brskanja. Prvi zapis prve strani ima zaporedno število 0.

Primer izhodnih podatkov, ko se iskanje še ne izvede. Podatki se uporabijo za izpis iskalne forme enostavnega iskanja.
Primer iskanja po nizu "test" in vseh organizacijah.
Primer uspešnega iskanja po COBISS (vrne URL za izvedbo iskanja na COBISS-u).
Primer neuspešnega iskanja po COBISS (vrne kodo sporočila).

Na vrh

urlAsQr

GET

Vrne QR kodo, ki predstavlja URL za ogled gradiva.

Vhod:

Parameter Opis
id ID gradiva.

Izhod:

PNG slika s QR kodo.

Na vrh