ISVU REST API v2 - HAL

Sadržaj

    Uvod

    Ova verzija ISVU REST API-ja implementira web servis temeljen na HATEOAS ograničenju REST arhitekture.

    Implementacija koristi Hypertext Application Language (HAL). HAL specifikacija na standardan i jednostavan način omogućava povezivanje između resursa. Koristeći HAL i standardne HTTP metode (GET, POST, PUT i DELETE) API je lakše čitljiv i programeru i aplikaciji koja ga koristi te time i lakši za korištenje, istraživanje API-ja te za razvoj klijentskih aplikacija.

    Početni URL je https://www.isvu.hr/api/. Svi ostali URL-ovi se mogu mijenjati kroz vrijeme.

    API definira koji se resurs nalazi iza kojeg linka. Link je jedinstveno odeređen svojim "rel" atributom. Svi objavljeni linkovi se neće mijenjati kroz vrijeme. URL na koji link pokazuje, "href" atribut, može se mijenjati kroz vrijeme.

    Reprezentacije resursa koje se nalaze na pojedinom URL-u mogu se proširivati kroz vrijeme. To naprimjer znači da ista reprezentacija može dodavati nove JSON name/value podatke, ali nikada neće mijenjati jednom objavljene JSON name/value podatke (Open content). Linkovi koje su izloženi kroz pojedinu reprezentaciju resursa mogu se mijenjati kroz vrijeme iako se to prvenstveno odnosi na dodavanje novih linkova.

    Reprezentacija resursa (Media Type)

    Trenutno je podržana JSON varijante HAL-a pod nazivom application/hal+json. Uz svaki link dodan je braem jedan primjer u application/hal+json varijanti. Zbog Open content principa, opisan u Uvodu, ne koristi se formalni opis reprezentacije kao što je XML Schema u verziji v1 ISVU REST API-ja.

    Linkovi

    Standardni korišteni linkovi, temeljeni na IANA Link Relations (http://www.iana.org/assignments/link-relations/link-relations.xhtml), su:

    Ukoliko nije drugačije navedeno, linkovi podržavaju GET HTTP metodu i to se neće posebno navoditi uz svaki link.

    URI Template

    Dio izloženih linkova, u skladu s HAL-om, definirani su sintaksom opisanom s URI Template standardom (https://tools.ietf.org/html/rfc6570). U takvom linku postoji barem jedan parametar koji je označen znakovima "{...}". Tako bi na primjeru linka "/api/vu/{sifraVisokogUcilista}/student/jmbag/{jmbag}" parametar "{sifraVisokogUcilista}"" označavao poziciju na koju treba dodati šifru visokog učilišta u ISVU, a oznaka "{jmbag}" poziciju na koju treba dodati JMBAG studenta za koga se traže podaci. Ovaj link je samo primjer i trenutno nije implementiran.

    Primjeri takvih linkova u ISVU REST API-ju:

    1. zavrsetakstudija_zavrsetakstudija_diploma
    2. zavrsetakstudija_zavrsetakstudija_dopunskaisprava

    Kako početi s korištenjem

    Generiranje zahtjeva može se obaviti putem REST API klijenta. Preporučamo korištenje klijenta DHC - REST/HTTP API Client koji se može dodati kao aplikacija unutar internet preglednika Google Chrome.

    Početni link za korištenje ove verzije ISVU REST API-ja isti je kao i prije (https://www.isvu.hr/api/), a obavezno je za traženu reprezentaciju resursa (Accept) navesti application/hal+json. Također, potrebna je i autorizacija pa u zaglavlje (Headers) treba dodati i korištenje autorizacije (Authorization) i to Basic Authorization te upisati podatke za prijavu Vašeg informacijskog sustava na ISVU REST API.

    Na slici možete vidjeti primjer GET zahtjeva za početnim linkom.

    Pomoću ovog klijenta može se dalje nastaviti pratiti dostupne linkove tako da kliknete na željeni link te pošaljete novi zahtjev klikom na gumb Send.

    HAL Browser

    Eksperimentalno smo pokrenuli HAL pretraživač (browser). HAL pretraživač je API klijent za hal+json reprezentaciju resursa.
    Dostupan je na stranici: https://www.isvu.hr/api/hal-browser/browser.html Potrebno je unesti URL resursa i Custom Request Header.
    Custom Request Header se npr. može dobiti tako da se u DHC-u upišu podaci za prijavu Vašeg informacijskog sustava (Authorization) i navede da je tražena reprezentacija resursa hal+json (application/hal+json). Zatim umjesto "form" odabrati prikaz "raw" i kopirati sve u Custom Request Header u HAL pretraživaču.
    Primjer podatka koji je potrebno kopirati u Custom Request Header:
    Authorization: Basic fgTzMyEtR6kjZgH9dTExjF4vrNlig0p=
    Content-Type: application/hal+json

    Politika ukidanja podrške pojedinog linka

    ISVU REST API je dizajniran i implementiran na način da podržava istovremeno više linkova vezanih za isti resurs. Obzirom da se API temelji na Open content principu, opisanog u Uvodu, ne očekujemo da će se biti česte potrebe za uvođenjem novih linkova za isti resurs. Na taj način je osigurano da uvođenje novog linka ne narušava kompatibilnost s postojećim informacijskim sustavima.

    Trajna podrška više linkova za jedan resurs nije održiva stoga je uvedena politika ukidanja podrške za pojedini link. Politika je da se podrška za pojedini link ukine 12 mjeseci nakon što se link označi "zastarjelim". Uz "zastarjele" linkove biti će crvenom bojom naveden datum kada će biti ukinuti, npr. (podržan do: 1. prosinca 2017.).

    ISVU REST API linkovi

    Odabirom pojedinog linka otvara se dokumentacija za taj link.

    Uz svaki novi link je zelenom bojom naveden mjesec uvođenja, npr. (siječanj 2016.).

    1. Početni link (index)

    2. Nastavni program

      1. nastavniprogram
      2. nastavniprogram_nastavniprogramuakademskimgodinama
      3. nastavniprogram_predavanjeizbornihpredmeta (kolovoz 2017.)
      4. nastavniprogram_predmeti
      5. nastavniprogram_studiji
      6. nastavniprogram_strukturastudija
      7. nastavniprogram_ess
      8. nastavniprogram_studijzaess
      9. nastavniprogram_korijenzaess
      10. nastavniprogram_ess_predmeti
      11. nastavniprogram_ess_obaveznipredmeti
      12. nastavniprogram_ess_grupaizbornihpredmeta
      13. nastavniprogram_ess_grupeizbornihpredmeta
      14. nastavniprogram_ess_grupeizbornihpredmeta_izbornipredmeti
      15. nastavniprogram_predmet
      16. nastavniprogram_predmet_preduvjeti
      17. nastavniprogram_predmet_ekvivalenti
      18. nastavniprogram_predmetuakademskojgodini
      19. nastavniprogram_predmetuakademskojgodini_opisi
      20. nastavniprogram_predmetuakademskojgodini_literature
      21. nastavniprogram_predmetuakademskojgodini_jezici
      22. nastavniprogram_predmetuakademskojgodini_ishodiucenja
      23. nastavniprogram_predmetuakademskojgodini_izvodjac
      24. nastavniprogram_predmetuakademskojgodini_izvodjac_grupe
      25. nastavniprogram_izvodjaci
      26. nastavniprogram_izvodjac_predmeti
      27. nastavniprogram_izmijenjeninastavniprogram
      28. nastavniprogram_izmijenjeninastavniprogram_dan_1
      29. nastavniprogram_izmijenjeninastavniprogram_dan_7
      30. nastavniprogram_izmijenjeninastavniprogram_dan_30
    3. Nastavni plan

      1. nastavniplan
      2. nastavniplan_nastavniplanzaakademskegodine
      3. nastavniplan_nastavniplanzaakademskugodinu
      4. nastavniplan_nastavniplanzaakademskugodinu_odrzanenastave (listopad 2016.)
      5. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava (listopad 2016.)
      6. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_izvodjaci (listopad 2016.)
      7. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_ishodiucenja (listopad 2016.)
      8. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_grupezanastavu (listopad 2016.)
      9. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_studenti (listopad 2016.)
      10. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_predmeti (listopad 2016.)
      11. nastavniplan_nastavniplanzaakademskugodinu_predmeti
      12. nastavniplan_nastavniplanzaakademskugodinu_predmeti_grupezanastavu
      13. nastavniplan_nastavniplanzaakademskugodinu_predmeti_grupezanastavu_grupazanastavu
      14. nastavniplan_nastavniplanzaakademskugodinu_predmeti_ispitnirokovi
      15. nastavniplan_nastavniplanzaakademskugodinu_predmeti_ispitnirok
      16. nastavniplan_nastavniplanzaakademskugodinu_predmeti_tjedniplannastave
      17. nastavniplan_nastavniplanzaakademskugodinu_predmeti_upisanistudenti
      18. nastavniplan_dozvole_dozvoledjelatnicimazapredmet
      19. nastavniplan_dozvole_dozvoledjelatnikunadpredmetima
      20. nastavniplan_dvorane (srpanj 2017.)
      21. nastavniplan_dvorana (srpanj 2017.)
      22. nastavniplan_izmijenjenigrupazanastavu
      23. nastavniplan_izmijenjenigrupazanastavu_dan_1
      24. nastavniplan_izmijenjenigrupazanastavu_dan_7
      25. nastavniplan_izmijenjenigrupazanastavu_dan_30
      26. nastavniplan_izmijenjeniispitnirok
      27. nastavniplan_izmijenjeniispitnirok_dan_1
      28. nastavniplan_izmijenjeniispitnirok_dan_7
      29. nastavniplan_izmijenjeniispitnirok_dan_30
    4. Student

      1. student
      2. student_student (podržan do: 1. kolovoza 2018.)
      3. student_student-v2 (srpanj 2017.)
      4. student_student_slika
      5. student_student_studentovstudij
      6. student_student_studentovprelazak
      7. student_student_aktivnost (podržan do: 1. prosinca 2017.)
      8. student_student_sumarnipodaci
      9. student_studentuakademskojgodini
      10. student_studentuakademskojgodini_studenti
      11. student_zabranaupisagodine_studenti
      12. student_zabranaupisagodine_student
      13. student_izmijenjenistudent
      14. student_izmijenjenistudent_dan_1
      15. student_izmijenjenistudent_dan_7
      16. student_izmijenjenistudent_dan_30
    5. Upis godine

      1. upisgodine
      2. upisgodine_upisgodineuakademskojgodini
      3. upisgodine_upisgodineuakademskojgodini_studenti
      4. upisgodine_student_upisanegodine
      5. upisgodine_student_upisgodine
      6. upisgodine_student_upisgodine_predmet
      7. upisgodine_student_upisgodine_predmet_izbornagrupa
      8. upisgodine_student_prekidi
      9. upisgodine_student_prekidi_prekid
      10. upisgodine_skolarine_student (studeni 2016.)
      11. upisgodine_skolarina_student (studeni 2016.)
      12. upisgodine_skolarina_student_transakcija (studeni 2016.)
      13. upisgodine_skolarina_student_rjesenjaopromjeniskolarine (studeni 2016.)
      14. upisgodine_skolarina_student_rjesenjeopromjeniskolarine (studeni 2016.)
      15. upisgodine_studentuakademskojgodini
      16. upisgodine_rezultatidrzavnematureuakademskojgodini (listopad 2017.)
      17. upisgodine_rezultatirazredbenogpostupkauakademskojgodini (listopad 2017.)
      18. upisgodine_studentuakademskojgodini_kategorijastudenta
      19. upisgodine_izmijenjeniupisgodine
      20. upisgodine_izmijenjeniupisgodine_dan_1
      21. upisgodine_izmijenjeniupisgodine_dan_7
      22. upisgodine_izmijenjeniupisgodine_dan_30
      23. upisgodine_izmijenjenistudentuakademskojgodini
      24. upisgodine_izmijenjenistudentuakademskojgodini_dan_1
      25. upisgodine_izmijenjenistudentuakademskojgodini_dan_7
      26. upisgodine_izmijenjenistudentuakademskojgodini_dan_30
    6. Osoba

      1. osoba
      2. osoba_osobe
      3. osoba_osobnipodaci
      4. osoba_izmijenjeniosoba (listopad 2016.)
      5. osoba_izmijenjeniosoba_dan_1 (listopad 2016.)
      6. osoba_izmijenjeniosoba_dan_7 (listopad 2016.)
      7. osoba_izmijenjeniosoba_dan_30 (listopad 2016.)
    7. Ustanova

      1. ustanova-v2 (lipanj 2017.)
      2. ustanova_ustanova (lipanj 2017.)
      3. ustanova_organizacijskajedinica (podržan do: 1. prosinca 2017.)
      4. ustanova_ustrojstvenajedinica (studeni 2016.)
      5. ustanova_centrivisokogucilista (listopad 2017.)
      6. ustanova_ustrojstvenejedinice (studeni 2016.)
      7. ustanova_vrstazabranenavu (studeni 2016.)
      8. ustanova_ogranicenja_dnevno (lipanj 2017.)
    8. Anketa

      (studeni 2016.)
      1. anketa
      2. anketa_anketauakademskimgodinama
      3. anketa_anketauakademskojgodini
      4. anketa_anketa
      5. anketa_anketa_rezultatiobrade
      6. anketa_anketa_rezultati
      7. anketa_anketa_nastavnici
      8. anketa_anketa_nastavnik_rezultati
      9. anketa_anketazasveucilisteuakademskimgodinama
      10. anketa_anketazasveucilisteuakademskojgodini
      11. anketa_anketazasveuciliste
      12. anketa_anketazasveuciliste_rezultatiobrade
      13. anketa_anketazasveuciliste_ustanovekojeizvodeanketu
      14. anketa_anketazasveuciliste_ustanovakojaizvodianketu_rezultatiobrade
    9. Novosti

      (studeni 2016.)
      1. novosti
      2. novosti_novostiukalendarskimgodinama
      3. novosti_novostiukalendarskojgodini
    10. Poslijediplomski studiji

      (studeni 2016.)
      1. pds_student_aktivnosti
      2. pds_student_aktivnost
      3. pds_student_zavrsniradovi
      4. pds_student_zavrsnirad
      5. pds_student_teme
      6. pds_student_tema
    11. Završetak studija

      (studeni 2016.)
      1. zavrsetakstudija
      2. zavrsetakstudija_temauakademskimgodinama
      3. zavrsetakstudija_temamentoruakademskimgodinama
      4. zavrsetakstudija_temauakademskojgodinizamentora
      5. zavrsetakstudija_tema
      6. zavrsetakstudija_tema_studenti
      7. zavrsetakstudija_zadatakpostudijima
      8. zavrsetakstudija_zadatakrokzaradzastudij
      9. zavrsetakstudija_zadatakrokzarad
      10. zavrsetakstudija_zadatakrokzaradstudenti
      11. zavrsetakstudija_zadatak
      12. zavrsetakstudija_rjesenjeoslobdiplpostudijima
      13. zavrsetakstudija_rjesenjeoslobdiplzastudij
      14. zavrsetakstudija_rjesenjeoslobdipl
      15. zavrsetakstudija_zavrsetakstudijauakademskimgodinama
      16. zavrsetakstudija_zavrsetakstudijauakademskojgodini
      17. zavrsetakstudija_zavrsetakstudija
      18. zavrsetakstudija_zavrsetakstudija_diploma
      19. zavrsetakstudija_zavrsetakstudija_diplomazadatum
      20. zavrsetakstudija_zavrsetakstudija_dopunskaisprava
      21. zavrsetakstudija_zavrsetakstudija_dopunskaispravazadatum
      22. zavrsetakstudija_zavrsetakstudija_dopunskaispravadefault
      23. zavrsetakstudija_zavrsetakstudija_dopunskaispravazadatumdefault
      24. zavrsetakstudija_izbormentorauakademskimgodinama
      25. zavrsetakstudija_izbormentorastudijuakademskojgodini
      26. zavrsetakstudija_izbormentorauakademskojgodinizastudij
      27. zavrsetakstudija_izbormentora
      28. zavrsetakstudija_izborpredmetauakademskimgodinama
      29. zavrsetakstudija_izborpredmetastudijuakademskojgodini
      30. zavrsetakstudija_izborpredmetauakademskojgodinizastudij
      31. zavrsetakstudija_izborpredmeta
      32. zavrsetakstudija_izbortemeuakademskimgodinama
      33. zavrsetakstudija_izbortemestudijuakademskojgodini
      34. zavrsetakstudija_izbortemeuakademskojgodinizastudij
      35. zavrsetakstudija_izborteme
      36. zavrsetakstudija_izmijenjenizavrsetakstudija
      37. zavrsetakstudija_izmijenjenizavrsetakstudija_dan_1
      38. zavrsetakstudija_izmijenjenizavrsetakstudija_dan_7
      39. zavrsetakstudija_izmijenjenizavrsetakstudija_dan_30
    12. Informacijski sustav

      (studeni 2016.)
      1. informacijskisustav
      2. informacijskisustav_dozvole
      3. informacijskisustav_kljucnerijeci
      4. informacijskisustav_preporuke
      5. informacijskisustav_dostupnozaustanove
    13. Višeinstitucijski informacijski sustavi

      (studeni 2016.)
      1. informacijskisustav_viseinstitucijski_student_jmbag
      2. informacijskisustav_viseinstitucijski_student_oib
      3. informacijskisustav_viseinstitucijski_student_uid
      4. informacijskisustav_viseinstitucijski_osoba_oznaka
      5. informacijskisustav_viseinstitucijski_osoba_uid
      6. informacijskisustav_viseinstitucijski_osoba_oib
    14. Ispit

      (ožujak 2017.)
      1. ispit
      2. ispit_izmijenjeniispit
      3. ispit_izmijenjeniispit_dan_1
      4. ispit_izmijenjeniispit_dan_7
      5. ispit_izmijenjeniispit_dan_30
      6. ispit_prijave
      7. ispit_prijava
      8. ispit_rezultatiusmenog
      9. ispit_rezultatusmenog
      10. ispit_studentibezpravanapotpisuakademskimgodinama
      11. ispit_studentibezpravanapotpisuakademskojgodini
      12. ispit_studentibezpravanapotpisusemestru
      13. ispit_studentibezpravanapotpiszapredmet
      14. ispit_studentibezpravanapotpis
      15. ispit_studentbezpravanapotpis
    15. Katalog

      1. katalog
      2. katalog_nastavniprogram_nacinizvedbestudija
      3. katalog_nastavniprogram_razinastudija
      4. katalog_nastavniprogram_tipelementastrukturestudija
      5. katalog_nastavniprogram_vrstanastavenavu
      6. katalog_nastavniprogram_vrstanastave
      7. katalog_nastavniprogram_vrstapravilaizbornegrupe
      8. katalog_nastavniprogram_tipindeksa
      9. katalog_nastavniprogram_znanstvenopodrucje (srpanj 2017.)
      10. katalog_nastavniplan_vrstaroka
      11. katalog_nastavniplan_odrzananastava_kategorijanastave (listopad 2016.)
      12. katalog_nastavniplan_tipdvorana (srpanj 2017.)
      13. katalog_osoba_strucninaziv
      14. katalog_osoba_duznost (studeni 2016.)
      15. katalog_ustanova_vrstaorganizacijskejedinice (podržan do: 1. prosinca 2017.)
      16. katalog_ustanova_vrstaustrojstvenejedinice (studeni 2016.)
      17. katalog_student_vrstazabrane
      18. katalog_student_razinapravanaprehranu
      19. katalog_student_razlogprestankaprava
      20. katalog_student_vrstaposebnogstatusa
      21. katalog_upisgodine_razlogprekidastudija
      22. katalog_upisgodine_razlogpromjeneskolarine (studeni 2016.)
      23. katalog_upisgodine_razlogneracunanjaponavljanja
      24. katalog_upisgodine_temeljfinanciranja
      25. katalog_upisgodine_statusupisanogpredmeta
      26. katalog_upisgodine_indikatorupisa
      27. katalog_upisgodine_nacinevidencijeupisnoglista
      28. katalog_upisgodine_nacinevidencijepredmeta
      29. katalog_upisgodine_nacinupisapredmeta
      30. katalog_upisgodine_nacinplacanja (studeni 2016.)
      31. katalog_upisgodine_polozajuzanimanju
      32. katalog_upisgodine_postignutoobrazovanje
      33. katalog_upisgodine_uzdrzavatelj
      34. katalog_upisgodine_zanimanje
      35. katalog_upisgodine_zdravstvenoosiguranje
      36. katalog_pds_kategorijaobveze
      37. katalog_pds_vrstazavrsetkastudija (studeni 2016.)
      38. katalog_pds_vrstazavrsnograda (studeni 2016.)
      39. katalog_anketa_objektprocjeneankete (studeni 2016.)
      40. katalog_anketa_tipelementizvjestajaankete (studeni 2016.)
      41. katalog_zavrsetakstudija_vrstateme (studeni 2016.)
      42. katalog_zavrsetakstudija_vrstadanazarad (studeni 2016.)
      43. katalog_zavrsetakstudija_pohvala (studeni 2016.)
      44. katalog_zavrsetakstudija_vrstadokumenta (studeni 2016.)
      45. katalog_strucnasprema
      46. katalog_jezik
      47. katalog_skole (srpanj 2017.)
      48. katalog_skola (srpanj 2017.)
      49. katalog_nacionalnost (kolovoz 2017.)
      50. katalog_strukovnopodrucje (kolovoz 2017.)
      51. katalog_programizobrazbe (kolovoz 2017.)
      52. katalog_razlogdirektnogupisa (kolovoz 2017.)
      53. katalog_vrstaliste (kolovoz 2017.)
      54. katalog_vrstaliste (kolovoz 2017.)
      55. katalog_ustrojstvenejedinice (rujan 2017.)
      56. katalog_ustrojstvenajedinica (rujan2017.)