Ovaj dokument opisuje ISVU REST API i izložene resurse. ISVU REST API je namijenjen programskoj interakciji s ISVU-om.
ISVU REST API bazira se na Hypertext Transfer Protocol-u (HTTP) opisanom na adresi http://www.w3.org/Protocols/. Svaki resurs ima barem jedan URL preko kojeg mu se pristupa. Za korištenje ISVU REST API-ja potrebno je obaviti HTTP zahtjev i obraditi odgovor. Kod poziva se koriste standardne HTTP metode: GET, POST, PUT i DELETE.
Kako se REST API bazira na otvorenim standardima, moguće je koristit praktički sve programske jezike za pristup API-ju.
ISVU REST API je općeniti API za pristup podacima i procedurama (resursima i metodama) pojedinog visokog učilišta u ISVU. API je dizajniran na način kako bi mogao obrađivati veliki broj zahtjeva raznih informacijskih sustava koji će ga koristiti. ISVU REST API se neće prilagođavati pojedinoj primjeni odnosno potrebama jednog informacijskog sustava zbog navedenih razloga.
Jedini mogući pristup ISVU REST API-ju je kroz kriptirani kanal (HTTP Secure - TLS).
Za sve informacije o ISVU REST API-ju možete se javiti na isvu@srce.hr.
Mailing lista api@srce.hr namijenjena je korisnicima ISVU REST API-ja. Kroz listu želi se omogućiti lakšu međusobnu komunikaciju korisnika ISVU REST API-ja kao i komunikaciju s ISVU Centrom potpore.
Pravila liste su:
Arhiva je dostupna na adresi https://list.srce.hr/mailman3/hyperkitty/list/api@srce.hr/.
Zahtjeve za dodavanjem na listu ISVU koordinatori šalju na isvu@srce.hr.
Modul za pregled informacijskih sustava ovlaštenih za spajanje na ISVU nalazi se na adresi https://www.isvu.hr/api/preglednik/.
Modul omogućuje pregled podataka za koje je njihov vlasnik odobrio objavu.
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. 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 evidentiranom rasponu, tada se zahtjev obrađuje, a inače se zahtjev odbija. Ukoliko raspon IP adresa nije evidentiran za pojedini informacijski sustav, 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:
Implementirane su dvije verzije ISVU REST API-ja: v1 i v2. Njihova implementacija je u skladu s Richardsonovim Maturity Modelom:
Verzija ISVU REST API-ja v2 u potpunosti pokriva sve funkcionalnosti verzije v1.
Verzija ISVU REST API v1 je proglašena zastarjelom te je podrška reprezentacije resursa te verzije ukinuta 1. veljače 2021.
Ova verzija ISVU REST API-ja implementira web servis temeljen na Hypermediji, konkretnije na HATEOAS ograničenju REST arhitekture. Ovakav REST API u Richardsonovom Maturity Modelu naziva se Level 3 - Hypermedia Controls.
Više o ovoj verziji i njezinim resursima možete naći u dokumentaciji.
Ova verzija ISVU REST API-ja implementira web servis temeljen na HTTP metodama (HTTP Methods) i reprezentaciji resursa (Media Type). Ovakav REST API u Richardsonovom Maturity Modelu naziva se Level 2 - HTTP Verbs.
ISVU REST API v1 je proglašen zastarjelim te je ukinut 1. veljače 2021.