Klijent PHP ISVU REST API (Pirac)

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.

Kategorija: