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@isvu.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 http://list.srce.hr/pipermail/api/.
Zahtjeve za dodavanjem na listu ISVU koordinatori šalju na isvu@srce.hr.
Jednom godišnje organizira se okupljanje korisnika ISVU REST API-ja.
Više o programu i održanim prezentacijama možete naći na adresi http://www.srce.unizg.hr/isvu/isvu-rest-api.
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.
Modul za analizu rada i korištenja nalazi se na adresi https://www.isvu.hr/api/analitika.
Modul je namijenjen:
Kroz modul izložene su sljedeće analize:
ISVU REST API je dostupan za produkcijski i za probni sustav na URL-ovima:
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."
Osnovna provjera (čitanje/GET) može se obaviti s internet preglednikom tako da se u adresnu traku upiše
URL resursa za koji se provjera želi obaviti. Internet preglednik će zatražiti korisničko ime i lozinku te,
ukoliko se autentikacija i autorizacija uspješno obave, ISVU REST API će vratiti traženi resurs i internet preglednik
će ga prikazati u odgovarajućem formatu. Da bi preglednik prikazao resurs u XML formatu,
obavezno je za traženu reprezentaciju resursa (Accept) navesti application/xhtml+xml i application/xml, dakle potrebno je zahtjevu postaviti zaglavlje Accept kao u primjeru:
Accept text/html,application/xhtml+xml,application/xml;
Ako se provjerava resurs 'ustanova' dovoljno je upisati URL https://www.isvu.hr/api/vu/{sifraUstanoveUIsvu}/ustanova.
Prvi primjer pokazuje zahtjev i odgovor kod GET metode za resurs o katalogu stručne spreme kod pristupa servisu korištenjem Firefox internet preglednika.
Zahtjev https://www.isvu.hr/api/vu/{sifraUstanoveUIsvu}/katalog/strucnasprema vraća
<strucneSpreme> <strucnaSprema sifra="1" kratica="NKV">Nekvalificiran</strucnaSprema> <strucnaSprema sifra="2" kratica="PKV">Polukvalificiran</strucnaSprema> <strucnaSprema sifra="3" kratica="KV">Kvalificiran</strucnaSprema> <strucnaSprema sifra="4" kratica="VKV">Visokokvalificiran</strucnaSprema> <strucnaSprema sifra="5" kratica="NSS">Niža stručna sprema</strucnaSprema> <strucnaSprema sifra="6" kratica="SSS">Srednja stručna sprema</strucnaSprema> <strucnaSprema sifra="7" kratica="VŠS">Viša stručna sprema</strucnaSprema> <strucnaSprema sifra="8" kratica="VSS">Visoka stručna sprema</strucnaSprema> <strucnaSprema sifra="9" kratica="MR">Magistar</strucnaSprema> <strucnaSprema sifra="10" kratica="DR">Doktor znanosti</strucnaSprema> </strucneSpreme>
HTTP Header zahtjeva:
GET /api/vu/123/katalog/strucnasprema HTTP/1.1 Host HOST:PORT User-Agent Mozilla/5.0 (Windows NT 6.1; WOW64; rv:8.0) Gecko/20100101 Firefox/8.0 Accept text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept-Language en-us,en;q=0.5 Accept-Encoding gzip, deflate Accept-Charset ISO-8859-1,utf-8;q=0.7,*;q=0.7 Connection keep-alive Authorization Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxx
HTTP Header odgovora:
HTTP/1.1 200 OK Server Apache-Coyote/1.1 Content-Type application/xml;charset=UTF-8 Transfer-Encoding chunked Date Fri, 16 Dec 2011 16:57:23 GMT
Kod POST metode odgovor će uvijek sadržavati HTTP Header Location s URL-om na kojem je dostupan novo stvoreni resurs, a HTTP Status Code odgovora će biti 201 Created.
Kod PUT metode se ne koristi HTTP Header Location u odgovoru jer se mijenja resurs na URL-u na koji je i poslan zahjev.
Primjer 1.
Korištenje HTTP POST i PUT metode zahtijeva postavljanje HTTP Header-a Content-Type na odgovarajuću vrijednost kao npr.
application/vnd.isvu.predakgodizvodjac.xml-v1.0+xml; charset=utf-8.
Primjer kod korištenja DHC - REST/HTTP API Client-a:
Primjer 2.
Idući primjer pokazuje zahtjev i odgovor kod POST metode za resurs o aktivnosti studenta poslijediplomskih studija kod pristupa servisu korištenjem DHC dodatka za Chrome internet preglednik.
POST zahtjevom https://www.isvu.hr/api/vu/{sifraUstanoveUIsvu}/student/aktivnost/jmbag/{jmbag} se za željenog studenta unosi aktivnost određene kategorije za određeni paralelni studij.
HTTP Header zahtjeva:
POST /api/vu/6/student/aktivnost/jmbag/xxxxxxxxxx HTTP/1.1 Host: HOST:PORT Authorization: Basic xxxxxxxxxxxxxxxxxxxxxxxxxxxx Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept-Encoding: gzip, deflate Accept-Language: hr-HR,hr;q=0.8,en-US;q=0.6,en;q=0.4,sr;q=0.2,sk;q=0.2,bs;q=0.2 Content-Type: application/vnd.isvu.aktivnoststudentapds.xml-v1.0+xml Content-Length: 259 Origin: chrome-extension://aejoelaoggembcahagimdiliamlcdmfm User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.152 Safari/537.36
Tijelo zahtjeva:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <aktivnostStudenta> <paralelniStudij>1</paralelniStudij> <kategorijaObveze sifra="1"/> <opisAktivnosti>Opis aktivnosti studenta</opisAktivnosti> <priznatoECTS>5.0</priznatoECTS> </aktivnostStudenta>
HTTP Header odgovora:
HTTP/1.1 201 Created Server: Apache-Coyote/1.1 Location: http://HOST:PORT/api/vu/6/student/aktivnost/jmbag/xxxxxxxxxx/paralelnistudij/1/kategorijaobveze/1 Content-Length: 0 Date: Thu, 21 May 2015 07:56:19 GMT
DELETE metodom se briše resurs na zadanom URL-u. U zahtjevu nije potrebno postavljati dodatne HTTP Header-e.
HTTP Status code odgovora će biti 204 No content i uvijek će sadržavati HTTP Header Location s
URL-om na koji ISVU REST API predlaže da klijent ode (GET zahtjev).
Primjer kod korištenja DHC - REST/HTTP API Client-a:
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:
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.
Više o ovoj verziji i njezinim resursima možete naći u dokumentaciji.