ISVU REST API je dostupan za produkcijski i za probni sustav na URL-ovima:
Za razvoj i testiranje preporučamo korištenje probnog sustava. Postupak za kreiranje pristupnih podataka i ovlasti identičan je za produkcijski i probni sustav te je opisana u poglavlju Ovlasti za korištenje servisa. Podaci se s produkcijskog sustava nekoliko puta godišnje prebacuju na probni sustav. Napomena: Podaci o klijentima ISVU REST API-ja (npr. korisničko ime i lozinka) ne prebacuju se s produkcijskog sustava na probni sustav nego je za probni sustav potrebno izdati nove pristupne podatke koristeći ISVU Admin Koordinator Probna.
Visoko učilište može samostalno kreirati pristupne podatke za korištenje ISVU REST API-ja te može definirati ovlasti pojedinog informacijskog sustava nad njihovim podacima i procedurama u ISVU. Detaljnije o administraciji pristupa moežete pročitati u ISVU uputama na adresi https://wiki.srce.hr/display/TUT/Administracija.
Visoko učilište ima ovlasti pristupati isključivo svojim podacima i procedurama te je dužno osigurati zaštitu podataka koje dobije putem ovog servisa.
Svaki zahtjev mora koristit Basic Authentication.
Zahtjev će biti autoriziran prema ovlastima definiranim za visoko učilište, kategoriju podataka te metodu (pregled ili rad s resursima).
Podržana su tri načina ograničenja korištenja servisa kako bi se onemogućilo eventualno pretjerano opterećenje kako aplikacijskih poslužitelja, tako i poslužitelja baze podataka, a time i omogućio nesmetan rad krajnjim korisnicima ISVU. To su:
Ograničenje po IP adresama za pojedinog klijenta temelji na IP adresi s koje je zahtjev poslan. Da biste aktivirali ovo ograničenje za svoje informacijske sustave potrebno je u modulu ISVU Admin koordinator evidentirati dozvoljeni raspon IP adresa (ili više njih). Detalji o evidenciji raspona IP adresa nalaze se na sljedećoj adresi: https://wiki.srce.hr/display/TUT/Informacijski+sustavi+za+REST+API.
U slučaju kada se IP adresa s koje je zahtjev poslan nalazi u nekom od evidentiranih raspona, tada se zahtjev obrađuje, a inače se zahtjev odbija. Ukoliko za pojedini informacijski sustav nije evidentiran niti jedan raspon IP adresa, to znači da se opisana provjera neće obavljati.
Odbijeni zahtjevi će dobiti odgovor s HTTP status kodom 403 Forbidden uz objašnjenje "Nije omogućena obrada zahtjeva jer niste ovlašteni za pristup s IP adrese ip_adresa s koje je došao zahtjev jer ona nije unutar dozvoljenog raspona."
Ograničenje se odnosi na broj zahtjeva koje svi klijenti ukupno mogu postaviti na razini dana nad resursima pojedinog visokog učilišta. Za svako visoko učilište određuje se maksimalan broj zahtjeva koji će biti obrađeni na razini dana za sve informacijske sustave tog visokog učilišta prema formuli 200 * broj_predmeta + 200 * broj_studenata. Kada se prekorači maksimalni broj zahtjeva, sljedeći zahtjevi u tom danu će se odbijati.
Ako je zahtjev odbijen jer je prekoračen maksimalan broj zahtjeva dnevno za visoko učilište, na zahtjev će biti odgovoreno HTTP status kodom 429 Too Many Requests uz objašnjenje "Nije omogućena obrada zahtjeva jer ste prekoračili dozvoljen broj zahtjeva za Vaše visoko učiliste na razini dana (max_broj_zahtjeva_na_razini_dana)."
Ograničenje se temelji na trenutnom opterećenju cijelog sustava, gdje krajnji korisnici ostalih ISVU modula (studenti, nastavnici i ostali korisnici) imati prioritet.
Ako je zahtjev odbijen jer je sustav preopterećen, na zahtjev će biti odgovoreno HTTP status kodom 503 Service Unavailable uz objašnjenje "Trenutno nije omogućena obrada zahtjeva zbog preopterećenosti sustava. Molimo pokušajte ponovo kroz nekoliko minuta."
Detaljnije upute kako započeti korištenje ISVU REST API-ja v2 dostupne su na adresi https://www.isvu.hr/api/dokumentacija/v2-hal/index.html#kako-poeti-s-koritenjem.
ISVU REST API je izložio resurse koji vraćaju popise izmijenjenih drugih resursa kao na primjer Popis studenata s izmijenjenim osnovnim podacima. U pravilu su izložena po tri resursa:
Tako, na primjeru izmijenjenih od jučerašnje ponoći, ako klijent pošalje zahtjev tijekom utorka, bez obzira u koje doba dana, ISVU REST API će vratiti sve resurse izmijenjene tijekom ponedjeljka (od 00:00:01) pa sve do trenutka u kojem je zahtjev obrađen.
Da bi se resurs pojavio u popisu izmijenjenih dovoljno je da nad tim resursom, tijekom perioda za koji se traže izmijenjeni obavljena jedna od akcija: brisanje, izmjena ili unos novog podatka. Nema garancije da će resurs biti izmijenjen jer nad njime može biti obavljeno više akcija koje u konačnici rezultiraju stanjem kakvo je bilo na početku promatranog intervala.
Ukoliko se izmjena obavila na nekom zavisnom resursu kao na primjer ispravljen je naziv mjesta rođenja, ali je ostao isti poštanski broj, studenti koji su rođeni u tom mjestu neće se pojaviti u popis izmijenjenih.
Ako je neki resurs obrisan, on će se naći u popisu, a klijent će onda dohvatom detalja tog resursa dobiti u odgovoru HTTP Status Code 404 što znači da to resursa više nema u sustavu.
Kako bi se povećala dostupnost sustava koji koriste ISVU REST API, kao i njihove performanse, preporuka je da sustavi koji su klijenti API-ja podatke iz ISVU koji su im potrebni za rad povremeno dohvaćaju i spremaju lokalno u klijentski sustav. Krajnji korisnici tih sustava trebali bi koristiti te lokalne podatke tako da ne ovise o ISVU REST API-ju (dostupnost API-ja, performanse, ...). Tipični primjer koji se uklapa u ovu preporuku su web stranice visokih učilišta na kojima se žele prikazivati podaci iz ISVU-a.
Period osvježavanja lokalnih podataka ovisi o konkretnoj primjeni, a često je sasvim dovoljno osvježiti podatke jednom dnevno. Neke primjene se vjerojatno neće moći uklopiti u ovaj model te je u takvim slučajevima posebno važno klijentske aplikacije izgraditi na način da znaju poštovati i obraditi vraćene HTTP Status Code-ove za zahtjeve koje klijentske aplikacije generiraju.
HTTP odgovori ISVU REST API-ja mogu biti kompresirani (HTTP compression)
kako bi se značajno smanjio HTTP promet između servera i klijenta.
Da bi odgovori bili kompresirani potrebno je u svakom HTTP zahtjevu postaviti HTTP Header Accept-Encoding s vrijednošću gzip
(Accept-Encoding: gzip). U odgovoru, ukoliko je on kompresiran, biti će postavljen HTTP Header Content-Encoding s
vrijednošću gzip (Content-Encoding: gzip). Nema garancije da će ISVU REST API sve zahtjeve kompresirati iako je klijent naveo
da podržava gzip-ane odgovore jer kod malih odgovora kompresija je suvišna i sl.
Primjer kod korištenja DHC - REST/HTTP API Client-a:
U slučaju problema u korištenju ISVU REST API-ja ponekad je potrebno provjeriti da li je pogreška u aplikaciji koja koristi ISVU REST API ili u ISVU REST API-ju. Za takve provjere preporučamo korištenje dodataka za internet preglednike. Primjeri za Google Chrome su 'Postman - REST Client', 'Dev HTTP Client' i 'Advanced REST client', a za Firefox 'Poster'.
Kada je problem u klijentskoj aplikaciji, obično se radi o sljedećim pogreškama:
Authorization HTTP Header.Accept HTTP Header kod GET zahtjeva.Content-Type HTTP Header kod POST i PUT zahtjeva.Ukoliko i korištenjem dodataka za internet preglednike niste dobili odgovor ISVU REST API-ja koji smatrate da je ispravan pošaljite e-mail na adresu isvu@srce.hr sa sljedećim informacijama: