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.

Seznam ukazov:

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

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č storitve. Če ključ ni naveden, se lahko dostopa do javno dosegljvih datotek.
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.

Izhod:

Vrne polni nabor metapodatkov gradiva v JSON ali JSONP obliki.

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 ReVIS.
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 ReVIS oz. prazen niz, če je.
Naziv	string	Ime datoteke, če je datoteka iz ReVIS oz. prazen niz, če ni.
PrenosPolniUrl	url	Polni URL za prenos datoteke v primeru, da je datoteka v ReVIS. 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).

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