U ovom članku prikazat će se primjer korištenja klijenta PHP ISVU REST API (Pirac) za programsku interakciju s Informacijskim sustavom visokih učilišta (ISVU). Članak je namijenjen početnicima i naprednim korisnicima. Početnicima može poslužiti kao primjer korištenja jednog PHP paketa za pristup ISVU REST API-ju, dok za napredne korisnike članak služi kao poziv na suradnju, komentiranje i dijeljenje programskih rješenja povezanih s akademskom zajednicom.
Što je Pirac
Pirac je mali paket napisan u PHP skriptnom jeziku, a služi za interakciju s ISVU-om. Interno Pirac koristi druge PHP pakete koji odrađuju „teži“ dio posla u komuniciranju s ISVU REST API-jem. Ustvari, Pirac je „omotač“ oko drugih PHP paketa, a smisao je da omogući brzo definiranje okruženja za pristup ISVU REST API-ju.
Glavni PHP paket koji Pirac koristi je klijent nategood/httpful HTTP. Pirac će sve zahtjeve (engl. requests) slati pomoću httpful paketa. Uz to Pirac koristi paket vlucas/phpdotenv koji služi za učitavanje varijabli okruženja iz .env tekstne datoteke.
Preduvjeti za Pirac
Za korištenje Pirac paketa potrebno je imati instaliran PHP >= 5.5.9.
Za slanje zahtjeva paket httpful koristi cURL PHP proširenje, pa je potrebno osigurati da je cURL PHP proširenje instalirano i omogućeno.
Pirac je organiziran kao Composer paket. Za instalaciju Pirac paketa potrebno je imati instaliran Composer Dependency Manager for PHP.
Za pristup ISVU REST API-ju potrebno je imati korisničko ime i lozinku. Dodatne informacije dostupne su na: https://www.isvu.hr/api/.
Primjer korištenja Pirac paketa
Instalacija
U ovom primjeru instalirat će se paket Pirac i napisati jednostavna PHP skripta u kojoj će se Pirac koristiti za dohvat podataka iz ISVU REST API-ja. Budući da Composer nije tema ovog članka, samo će se navesti potrebne naredbe za instalaciju i uključivanje Pirac paketa u projekt, neće se ići u detalje.
Prvi korak jest napraviti direktorij u koji će se spremiti sve datoteke. U ovom primjeru direktorij će se zvati „pirac-demo“. U ovom trenutku direktorij „pirac-demo“ potpuno je prazan.
Dalje, potrebno je otvoriti komandnu liniju i postaviti se u direktorij „pirac-demo“. Nakon toga potrebno je unijeti naredbu:
composer require cicnavi/pirac:“dev-master“
Gore navedena naredba pokrenut će instalaciju paketa Pirac.
Direktorij „pirac-demo“ sada će sadržavati dvije nove datoteke i direktorij vendor.
Konfiguracija i inicijalizacija
U dokumentaciji Piraca vidljivo je da je u korijenskom direktoriju projekta (engl. root directory) potrebno stvoriti datoteku .env i u njoj definirati pristupne podatke za ISVU REST API. Za produkcijski API potrebno je definirati varijable kako slijedi:
ISVU_USERNAME=nekoKorisnickoIme
ISVU_PASSWORD=nekaLozinka
Pirac može koristiti i testni API. Za korištenje testnog API-ja potrebno je definirati dodatne varijable kako slijedi:
ISVU_USE_TEST_API=true
ISVU_TEST_USERNAME= nekoKorisnickoIme
ISVU_TEST_PASSWORD= nekaLozinka
Dakle, sve te varijable mogu biti definirane u datoteci .env, a selektiranje između produkcijskog i testnog API-ja može se obavljati preko varijable „ISVU_USE_TEST_API“.
Primjer datoteke .env u direktoriju „pirac-demo“:
Sljedeći korak je stvaranje skripte index.php unutar direktorija „pirac-demo“. Ta skripta će biti ulaz u aplikaciju.
Composer pruža automatsko generiranu klasu za uključivanje vanjskih paketa u aplikaciju. Ta klasa nalazi se u direktoriju vendor i može se uključiti pomoću sljedeće linije:
require __DIR__.'/vendor/autoload.php';
Dakle, gore navedenu liniju potrebno je unijeti na početku skripte index.php. Nakon toga moguće je navesti korištenje Pirac paketa u skripti pomoću linije:
use Pirac\Pirac;
Nakon toga moguće je stvoriti Pirac instancu pomoću linije:
$pirac = new Pirac();
U ovom trenutku datoteka index.php izgleda ovako:
Piracove metode
getIndex() metoda
Prema početnim postavkama Pirac koristi ISVU REST API verziju 2. To znači da Pirac može saznati linkove resursa iz samog API-ja. Pirac ima sljedeću metodu za dohvat linkova prema početnim resursima u ISVU REST API-ju:
$pirac->getIndex();
Primjer getIndex() metode u index.php skripti:
U gornjem primjeru rezultat getIndex() metode spremljen je u varijablu $indexLinks.
U ovom trenutku može se provjeriti kako skripta index.php radi. U tu svrhu može se iskoristiti i PHP ugrađeni poslužitelj. Za pokretanje ugrađenog poslužitelja u komandnoj liniji potrebno je unijeti naredbu:
php -S localhost:8000
Naredbu je potrebno pokrenuti unutar direktorija „pirac-demo“. Nakon toga moguće je dohvatiti stranicu tako da se u pregledniku unese adresa „localhost:8000“. Automatski će se pokrenuti skripta index.php, a var_dump($indexLinks) linija će dati sljedeći ispis:
Na gornjoj slici vidljivo je da je Pirac vratio standardni PHP objekt (stdClass instanca) u kojem su navedeni početni resursi i njihovi linkovi kao javna svojstva tog objekta.
get() metoda
Početne linkove koji su dohvaćeni getIndex() metodom, naravno, moguće je dalje koristiti u skripti. Pirac ima sljedeću metodu za dohvat ostalih resursa:
$pirac->get($url);
Dakle, get() metoda u prvom parametru prima string koji treba sadržavati URL na određeni resurs.
Za primjer, neka Pirac dohvati resurs 'nastavniplan' i spremi u varijablu $nastavniplan. Za URL koristit će se prethodno stvorena $indexLinks varijabla i njeno svojstvo nastavniplan->href koje sadrži URL string. Skripta sada izgleda ovako:
Varijabla $nastavniplan sada sadrži novi objekt s novim linkovima na resurse. Linija var_dump($nastavniplan) daje sljedeći ispis:
Ako se gornji primjer objekta usporedi s JSON odgovorom koji vrati API, vidljivo je da Pirac stvara standardni PHP objekt iz vraćenog JSON odgovora. JSON odgovor iz kojeg je Pirac napravio stdClass objekt prikazan je ispod:
Dakle, Pirac će iz svakog JSON odgovora stvoriti objekt koji se lako može koristiti u nastavku aplikacije. Tim principom može se doći do svih ostalih željenih podataka iz ISVU REST API-ja.
Pirac i ISVU REST API verzija 1
Iako po početnim postavkama Pirac komunicira s verzijom 2 ISVU REST API-ja, Pirac može komunicirati i s verzijom 1 ISVU REST API-ja.
Kao početnu vrijednost Accept HTTP zaglavlja Pirac koristi string 'application/hal+json', što indirektno znači korištenje ISVU REST API-ja verzije 2.
Pirac metoda get() prima i drugi parametar tipa polje (engl. array). U tom polju moguće je navesti HTTP zaglavlja koja želimo koristiti pri slanju zahtjeva prema API-ju. Dakle, u drugom parametru moguće je navesti i zaglavlje Accept koje će se koristiti. Ako se navede zaglavlje Accept koje se koristi u verziji 1 ISVU REST API-ja, ISVU će automatski odgovoriti s API verzije 1.
Na primjer, neka Pirac dohvati URL: 'https://www.isvu.hr/apiproba/vu/65/nastavniplan/student/predmet/71274/akademskagodina/2016/semestar/1/1/1'. Neka zaglavlje Accept bude: 'application/xml'.
Budući da ISVU REST API verzija 1 vraća XML string, Pirac će vratiti drugačiji odgovor:
Na donjoj slici prikazan je XML odgovor koji vraća ISVU REST API 1, pa je moguće vidjeti na koji način Pirac stvara SimpleXMLElement objekt.
Višeinstitucijski API
Pirac može raditi i s višeinstitucijskim ISVU REST API-jem, samo što se getIndex() Pirac metoda ponaša drugačije. U jednoinstitucijskom API-ju ta metoda odmah vraća resurse i linkove za onu instituciju za koju naš API ima pravo pristupa. Kod višeinstitucijskog API-ja, getIndex() metoda će vratiti sve institucije u polju (engl. array).
Na sljedećem primjeru koristi se višeinstitucijski API:
Sada je moguće odabrati instituciju tako da se definira ključ određene institucije iz polja.
Na primjer, recimo da se želi odabrati prva institucija:
$institutionIndexLinks = $indexLinks[0];
Ostale napomene
Trenutačno Pirac nudi samo mogućnost čitanja podataka iz ISVU REST API-ja (GET metoda). Ovisno o tome pokaže li se Pirac korisnim zajednici, krenut će se u implementaciju i ostalih HTTP metoda.
U trenutku pisanja ovog članka Pirac nema označenu verziju paketa, nego se za instalaciju koristi razvojna verzija „dev-master“. Pirac će naknadno dobiti prvu oznaku stabilne verzije.
Pirac je dostupan pod licencom MIT.