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 određ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 barem 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
      4. nastavniprogram_predmeti
      5. nastavniprogram_studiji
      6. nastavniprogram_obrazovniprogrami (siječanj 2019.)
      7. nastavniprogram_strukturastudija
      8. nastavniprogram_ess
      9. nastavniprogram_studijzaess
      10. nastavniprogram_korijenzaess
      11. nastavniprogram_ess_predmeti
      12. nastavniprogram_ess_obaveznipredmeti
      13. nastavniprogram_ess_grupaizbornihpredmeta
      14. nastavniprogram_ess_grupeizbornihpredmeta
      15. nastavniprogram_ess_grupeizbornihpredmeta_izbornipredmeti
      16. nastavniprogram_parametristudijauakademskojgodini (srpanj 2018.)
      17. nastavniprogram_predmet
      18. nastavniprogram_predmet_preduvjeti
      19. nastavniprogram_predmet_ekvivalenti
      20. nastavniprogram_predmetuakademskojgodini
      21. nastavniprogram_predmetuakademskojgodini_opisi
      22. nastavniprogram_predmetuakademskojgodini_literature
      23. nastavniprogram_predmetuakademskojgodini_jezici
      24. nastavniprogram_predmetuakademskojgodini_ishodiucenja
      25. nastavniprogram_predmetuakademskojgodini_izvodjac
      26. nastavniprogram_predmetuakademskojgodini_izvodjac_grupe
      27. nastavniprogram_izvodjaci
      28. nastavniprogram_izvodjac_predmeti
      29. nastavniprogram_izvodjacuakademskimgodinama
      30. nastavniprogram_izmijenjeninastavniprogram
      31. nastavniprogram_izmijenjeninastavniprogram_dan_1
      32. nastavniprogram_izmijenjeninastavniprogram_dan_7
      33. nastavniprogram_izmijenjeninastavniprogram_dan_30
    3. Nastavni plan

      1. nastavniplan
      2. nastavniplan_nastavniplanzaakademskegodine
      3. nastavniplan_nastavniplanzaakademskugodinu
      4. nastavniplan_nastavniplanzaakademskugodinu_odrzanenastave
      5. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava
      6. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_izvodjaci
      7. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_ishodiucenja
      8. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_grupezanastavu
      9. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_studenti
      10. nastavniplan_nastavniplanzaakademskugodinu_odrzananastava_predmeti
      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
      21. nastavniplan_dvorana
      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
      4. student_student_slika
      5. student_student_studentovstudij
      6. student_student_studentovprelazak (podržan do: 1. rujna 2019.)
      7. student_student_prelazakstudentanavu (kolovoz 2018.)
      8. student_student_aktivnost (podržan do: 1. prosinca 2017.)
      9. student_student_sumarnipodaci
      10. student_studentuakademskojgodini
      11. student_studentuakademskojgodini_studenti
      12. student_zabranaupisagodine_studenti
      13. student_zabranaupisagodine_student
      14. student_izmijenjenistudent
      15. student_izmijenjenistudent_dan_1
      16. student_izmijenjenistudent_dan_7
      17. 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
      11. upisgodine_skolarina_student
      12. upisgodine_skolarina_student_transakcija
      13. upisgodine_skolarina_student_rjesenjaopromjeniskolarine
      14. upisgodine_skolarina_student_rjesenjeopromjeniskolarine
      15. upisgodine_studentuakademskojgodini
      16. upisgodine_studentuakademskojgodini_kategorijastudenta
      17. upisgodine_rezultatidrzavnematureuakademskojgodini
      18. upisgodine_rezultatirazredbenogpostupkauakademskojgodini
      19. upisgodine_naknadnoevidentiranjeocjena
      20. upisgodine_naknadnoevidentiranjeocjena_student
      21. upisgodine_izmijenjeniupisgodine
      22. upisgodine_izmijenjeniupisgodine_dan_1
      23. upisgodine_izmijenjeniupisgodine_dan_7
      24. upisgodine_izmijenjeniupisgodine_dan_30
      25. upisgodine_izmijenjenistudentuakademskojgodini
      26. upisgodine_izmijenjenistudentuakademskojgodini_dan_1
      27. upisgodine_izmijenjenistudentuakademskojgodini_dan_7
      28. upisgodine_izmijenjenistudentuakademskojgodini_dan_30
    6. Osoba

      1. osoba
      2. osoba_osobe
      3. osoba_osobnipodaci
      4. osoba_mobilnost
      5. osoba_akademskistupanj
      6. osoba_strucnasprema
      7. osoba_strucninaziv
      8. osoba_statuszaposlenja
      9. osoba_zvanje
      10. osoba_izmijenjeniosoba
      11. osoba_izmijenjeniosoba_dan_1
      12. osoba_izmijenjeniosoba_dan_7
      13. osoba_izmijenjeniosoba_dan_30
    7. Ustanova

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

      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

      1. novosti
      2. novosti_novostiukalendarskimgodinama
      3. novosti_novostiukalendarskojgodini
    10. Poslijediplomski studiji

      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

      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

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

      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

      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_rezultatipismenog
      11. ispit_rezultatpismenog
      12. ispit_studentibezpravanapotpisuakademskimgodinama
      13. ispit_studentibezpravanapotpisuakademskojgodini
      14. ispit_studentibezpravanapotpisusemestru
      15. ispit_studentibezpravanapotpiszapredmet
      16. ispit_studentibezpravanapotpis
      17. 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
      10. katalog_nastavniplan_vrstaroka
      11. katalog_nastavniplan_odrzananastava_kategorijanastave
      12. katalog_nastavniplan_tipdvorana
      13. katalog_osoba_akademskistupanj
      14. katalog_osoba_statuszaposlenja
      15. katalog_osoba_strucninaziv
      16. katalog_osoba_zvanje
      17. katalog_osoba_duznost
      18. katalog_ustanova_vrstaorganizacijskejedinice (podržan do: 1. prosinca 2017.)
      19. katalog_ustanova_vrstaustrojstvenejedinice
      20. katalog_student_vrstazabrane
      21. katalog_student_razinapravanaprehranu
      22. katalog_student_razlogprestankaprava
      23. katalog_student_vrstaposebnogstatusa
      24. katalog_upisgodine_razlogprekidastudija
      25. katalog_upisgodine_razlogpromjeneskolarine
      26. katalog_upisgodine_razlogneracunanjaponavljanja
      27. katalog_upisgodine_temeljfinanciranja
      28. katalog_upisgodine_statusupisanogpredmeta
      29. katalog_upisgodine_indikatorupisa
      30. katalog_upisgodine_nacinevidencijeupisnoglista
      31. katalog_upisgodine_nacinevidencijepredmeta
      32. katalog_upisgodine_nacinupisapredmeta
      33. katalog_upisgodine_nacinplacanja
      34. katalog_upisgodine_polozajuzanimanju
      35. katalog_upisgodine_postignutoobrazovanje
      36. katalog_upisgodine_uzdrzavatelj
      37. katalog_upisgodine_zanimanje
      38. katalog_upisgodine_zdravstvenoosiguranje
      39. katalog_pds_kategorijaobveze
      40. katalog_pds_vrstazavrsetkastudija
      41. katalog_pds_vrstazavrsnograda
      42. katalog_anketa_objektprocjeneankete
      43. katalog_anketa_tipelementizvjestajaankete
      44. katalog_zavrsetakstudija_vrstateme
      45. katalog_zavrsetakstudija_vrstadanazarad
      46. katalog_zavrsetakstudija_pohvala
      47. katalog_zavrsetakstudija_vrstadokumenta
      48. katalog_strucnasprema
      49. katalog_jezik
      50. katalog_skole
      51. katalog_skola
      52. katalog_nacionalnost
      53. katalog_strukovnopodrucje
      54. katalog_programizobrazbe
      55. katalog_programmobilnosti
      56. katalog_razlogdirektnogupisa
      57. katalog_vrstaliste
      58. katalog_vrstaliste
      59. katalog_ustrojstvenejedinice
      60. katalog_ustrojstvenajedinica