ISVU REST API Dokumentacija

Sadržaj

    Osnovne informacije

    Uvod

    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).

    Kontakt

    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.

    Okupljanje korisnika ISVU REST API-ja

    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.

    Informacije o korištenju API-ja

    Preglednik informacijskih sustava ovlaštenih za spajanje na ISVU

    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.

    Preglednik informacijskih sustava ovlaštenih za spajanje na ISVU

    Analiza rada i korištenja

    Modul za analizu rada i korištenja nalazi se na adresi https://www.isvu.hr/api/analitika.

    Modul je namijenjen:

    Analiza rada i korištenja

    Kroz modul izložene su sljedeće analize:

    Više o modulu: https://wiki.srce.hr/pages/viewpage.action?pageId=1671234

    Upute za korištenje API-ja

    Produkcijski i probni sustav

    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.

    Ovlasti za korištenje servisa

    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.

    Autentikacija i autorizacija

    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).

    Ograničenja pri korištenju servisa

    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:

    1. ograničenje po IP adresama za pojedinog klijenta,
    2. ograničenje ukupnog broja zahtjeva po danu za visoko učilište,
    3. ograničenje zbog preopterećenosti sustava.

    Ograničenje po IP adresama

    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 ukupnog broja zahtjeva po danu za visoko učilište

    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 zbog preopterećenosti sustava

    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."

    Kako početi s korištenjem

    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.

    Primjer za GET metodu

    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
    

    Primjer za POST ili PUT metodu

    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:
    Prikaz korištenja HTTP POST i PUT metode

    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
    

    Primjer za DELETE

    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:
    Prikaz korištenja HTTP DELETE metode

    Resursi tipa "izmijenjeni"

    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.

    Preporuke o načinu korištenja

    Period osvježavanja podataka

    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 kompresija

    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:
    Prikaz korištenja HTTP kompresije

    Kako provjeriti ponašanje ISVU REST API-ja i prijaviti pogrešku

    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:

    1. Nije postavljen Authorization HTTP Header.
    2. Nije postavljen Accept HTTP Header kod GET zahtjeva.
    3. Nije postavljen Content-Type HTTP Header kod POST i PUT zahtjeva.
    4. U slučaju 4xx HTTP Status Code-a tijelo odgovora (body) uglavnom sadrži detaljan opis pogreške.

    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:

    1. Da li se radi o produkcijskom ili probnom ISVU REST API-ju.
    2. Vrijeme kada ste obavili zahtjev.
    3. Puni URL zahtjeva.
    4. Korisničko ime s kojim se aplikacija spaja.
    5. IP adresu s koje se aplikacija spaja.
    6. Korištenu HTTP metodu.
    7. Request Accept Header.
    8. Request Content-Type Header (kod POST i PUT zahtjeva).
    9. Response Content Type Header.
    10. HTTP Status Code odgovora.
    11. HTTP Message odgovora.
    12. Sadržaj odgovora.
    13. Sadržaj koji je poslan uz POST ili PUT zahtjev.
    14. Sve ostale HTTP Header-e koje ste postavili u zahtjevu.
    15. Sliku ekrana nekog od dodataka internet preglednicima u kojima je reproducirana potencijalna pogreška (poželjno).

    Verzije ISVU REST API-ja

    Implementirane su dvije verzije ISVU REST API-ja: v1 i v2. Njihova implementacija je u skladu s Richardsonovim Maturity Modelom:

    Planira se postepeni prelazak na ISVU REST API v2, a taj proces će trajati duže vrijeme dok verzija v2 ne pokrije u potpunosti funkcionalnosti verzije v1 i uz poštivanje Politike ukidanja podrške pojedine verzije reprezentacije resursa.

    ISVU REST API v2

    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.

    ISVU REST API v1

    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.