ISVU REST API v2 - HAL

Sadržaj

Izjava o pristupačnosti

    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.

    Postoje resursi kojima je podržani format XML, primjerice zavrsetakstudija_zavrsetakstudija_diploma. Takvi resursi imaju minimalno dvije reprezentacije, jednu specifičnu za taj resurs, kao npr. application/vnd.isvu.svjedodzbadiploma.xml-v1.1+xml, i drugu, generičku, reprezentaciju application/xml.
    Resurs može imati i više specifičnih reprezentacija. Svaka takva reprezentacija definira XML Schemu koja se koristi. Pripadna XML Schema (ili više njih) biti će navedena na stranici dokumentacije za konkretni resurs, uz eventualni datum do kada je podržana, ako je podržano više specifičnih reprezentacija, u skladu s Politikom ukidanja podrške pojedinog linka.
    Preporuka je da klijentske aplikacije koriste konkretnu specifičnu reprezentaciju, jer na taj način ne bi imale problema kod dodavanja novih verzija reprezentacija pojedinog resursa.
    Ukoliko postoji više specifičnih reprezentacija istog resursa kao npr. application/vnd.isvu.svjedodzbadiploma.xml-v1.0+xml i application/vnd.isvu.svjedodzbadiploma.xml-v1.1+xml, reprezentacija application/xml će uvijek vraćati najnoviju verziju. Time se olakšava razvoj, testiranje i istraživanje.

    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 Talend API Tester 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.

    Primjer za GET metodu

    Na slici možete vidjeti primjer GET zahtjeva i odgovora.

    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.

    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 za DELETE

    DELETE metodom se briše resurs na zadanom URL-u. U zahtjevu nije potrebno postavljati dodatne HTTP Header-e.

    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 Talend-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
      7. nastavniprogram_strukturastudija
      8. nastavniprogram_ess
      9. nastavniprogram_studij_centrivisokogucilista
      10. nastavniprogram_studijzaess
      11. nastavniprogram_korijenzaess
      12. nastavniprogram_ess_predmeti
      13. nastavniprogram_ess_obaveznipredmeti
      14. nastavniprogram_ess_izbornipredmeti
      15. nastavniprogram_ess_grupaizbornihpredmeta
      16. nastavniprogram_ess_grupeizbornihpredmeta
      17. nastavniprogram_ess_grupeizbornihpredmeta_izbornipredmeti
      18. nastavniprogram_parametristudijauakademskojgodini
      19. nastavniprogram_predmet
      20. nastavniprogram_predmet_preduvjeti
      21. nastavniprogram_predmet_ekvivalenti
      22. nastavniprogram_predmetuakademskojgodini
      23. nastavniprogram_predmetuakademskojgodini_opisi
      24. nastavniprogram_predmetuakademskojgodini_literature
      25. nastavniprogram_predmetuakademskojgodini_jezici
      26. nastavniprogram_predmetuakademskojgodini_ishodiucenja
      27. nastavniprogram_predmetuakademskojgodini_izvodjac
      28. nastavniprogram_predmetuakademskojgodini_izvodjac_grupe
      29. nastavniprogram_izvodjaci
      30. nastavniprogram_izvodjac_predmeti
      31. nastavniprogram_izvodjacuakademskimgodinama
      32. nastavniprogram_izmijenjeninastavniprogram
      33. nastavniprogram_izmijenjeninastavniprogram_dan_1
      34. nastavniprogram_izmijenjeninastavniprogram_dan_7
      35. nastavniprogram_izmijenjeninastavniprogram_dan_30
      36. nastavniprogram_ishodiucenjastudprog
      37. nastavniprogram_ishodiucenjastudprogakgod

    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-v2
      3. student_student-v2_oib
      4. student_student-v2_uid
      5. student_student_slika
      6. student_student_studentovstudij
      7. student_student_prelazakstudentanavu
      8. student_student_sumarnipodaci
      9. student_studentuakademskojgodini
      10. student_studentuakademskojgodini_studenti
      11. student_zabranastudentu_studenti
      12. student_zabranastudentu_student
      13. student_zabranaupisagodine_studenti
      14. student_zabranaupisagodine_student
      15. student_ispisanistudentiukalendarskojgodini (siječanj 2022.)
      16. student_ispisanistudentiukalendarskojgodini_studenti (siječanj 2022.)
      17. student_izmijenjenistudent
      18. student_izmijenjenistudent_dan_1
      19. student_izmijenjenistudent_dan_7
      20. 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_stornotransakcije
      14. upisgodine_skolarina_student_rjesenjaopromjeniskolarine
      15. upisgodine_skolarina_student_rjesenjeopromjeniskolarine
      16. upisgodine_studentuakademskojgodini
      17. upisgodine_studentuakademskojgodini_kategorijastudenta
      18. upisgodine_rezultatidrzavnematureuakademskojgodini
      19. upisgodine_rezultatirazredbenogpostupkauakademskojgodini
      20. upisgodine_naknadnoevidentiranjeocjena
      21. upisgodine_naknadnoevidentiranjeocjena_student
      22. upisgodine_priznavanjeispita
      23. upisgodine_priznavanjeispita_student
      24. upisgodine_studentskidomoviuakademskojgodini
      25. upisgodine_studentskidomstudenta
      26. upisgodine_aktivnoststudentaprijeupisanastudij
      27. upisgodine_aktivnoststudentaprijeupisanastudij_student
      28. upisgodine_priznavanjeectsbodovaipredmeta
      29. upisgodine_priznavanjeectsbodovaipredmeta_student
      30. upisgodine_boravakstudenataizvanmaticnogvu
      31. upisgodine_boravakstudenataizvanmaticnogvu_boravak
      32. upisgodine_izmijenjeniupisgodine
      33. upisgodine_izmijenjeniupisgodine_dan_1
      34. upisgodine_izmijenjeniupisgodine_dan_7
      35. upisgodine_izmijenjeniupisgodine_dan_30
      36. upisgodine_izmijenjenistudentuakademskojgodini
      37. upisgodine_izmijenjenistudentuakademskojgodini_dan_1
      38. upisgodine_izmijenjenistudentuakademskojgodini_dan_7
      39. upisgodine_izmijenjenistudentuakademskojgodini_dan_30

    6. 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_prijavezastudentazapredmet
      9. ispit_rezultatiusmenog
      10. ispit_rezultatusmenog
      11. ispit_rezultatipismenog
      12. ispit_rezultatpismenog
      13. ispit_studentibezpravanapotpisuakademskimgodinama
      14. ispit_studentibezpravanapotpisuakademskojgodini
      15. ispit_studentibezpravanapotpisusemestru
      16. ispit_studentibezpravanapotpiszapredmet
      17. ispit_studentibezpravanapotpis
      18. ispit_studentbezpravanapotpis
      19. ispit_ocjena_ects

    7. Osoba

      1. osoba
      2. osoba_osobe
      3. osoba_osobnipodaci
      4. osoba_osobnipodaci_uid
      5. osoba_osobnipodaci_oib
      6. osoba_mobilnost
      7. osoba_akademskistupanj
      8. osoba_strucnasprema
      9. osoba_strucninaziv
      10. osoba_statuszaposlenja
      11. osoba_zvanje
      12. osoba_zvanje_zatvaranjeotvaranje
      13. osoba_izmijenjeniosoba
      14. osoba_izmijenjeniosoba_dan_1
      15. osoba_izmijenjeniosoba_dan_7
      16. osoba_izmijenjeniosoba_dan_30

    8. Ustanova

      1. ustanova-v2
      2. ustanova_ustanova
      3. ustanova_ustrojstvenajedinica
      4. ustanova_centrivisokogucilista
      5. ustanova_ustrojstvenejedinice
      6. ustanova_vrstazabranenavu
      7. ustanova_ogranicenja_dnevno

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

    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_student_zadaci
      12. zavrsetakstudija_zadatak
      13. zavrsetakstudija_rjesenjeoslobdiplpostudijima
      14. zavrsetakstudija_rjesenjeoslobdiplzastudij
      15. zavrsetakstudija_rjesenjeoslobdipl
      16. zavrsetakstudija_zavrsetakstudijauakademskimgodinama
      17. zavrsetakstudija_zavrsetakstudijauakademskojgodini
      18. zavrsetakstudija_zavrsetakstudija
      19. zavrsetakstudija_zavrsetakstudija_diploma
      20. zavrsetakstudija_zavrsetakstudija_diplomazadatum
      21. zavrsetakstudija_zavrsetakstudija_dopunskaisprava
      22. zavrsetakstudija_zavrsetakstudija_dopunskaispravazadatum
      23. zavrsetakstudija_zavrsetakstudija_dopunskaispravadefault
      24. zavrsetakstudija_zavrsetakstudija_dopunskaispravazadatumdefault
      25. zavrsetakstudija_izbormentorauakademskimgodinama
      26. zavrsetakstudija_izbormentorastudijuakademskojgodini
      27. zavrsetakstudija_izbormentorauakademskojgodinizastudij
      28. zavrsetakstudija_izbormentora
      29. zavrsetakstudija_izborpredmetauakademskimgodinama
      30. zavrsetakstudija_izborpredmetastudijuakademskojgodini
      31. zavrsetakstudija_izborpredmetauakademskojgodinizastudij
      32. zavrsetakstudija_izborpredmeta
      33. zavrsetakstudija_izbortemeuakademskimgodinama
      34. zavrsetakstudija_izbortemestudijuakademskojgodini
      35. zavrsetakstudija_izbortemeuakademskojgodinizastudij
      36. zavrsetakstudija_izborteme
      37. zavrsetakstudija_mentor_studenti
      38. zavrsetakstudija_izmijenjenizavrsetakstudija
      39. zavrsetakstudija_izmijenjenizavrsetakstudija_dan_1
      40. zavrsetakstudija_izmijenjenizavrsetakstudija_dan_7
      41. zavrsetakstudija_izmijenjenizavrsetakstudija_dan_30
      42. zavrsetakstudija_dodatnipodacidopunska
      43. zavrsetakstudija_dodatnipodacidopunskadatum

    12. Mreža sveučilišta (lipanj 2023.)

      1. mrezasveucilista
      2. mrezasveucilista_mreze
      3. mrezasveucilista_mreza
      4. mrezasveucilista_mreza_ponudapredmeta
      5. mrezasveucilista_student
      6. mrezasveucilista_student_predmet
      7. mrezasveucilista_student_predmet_ispit

    13. Informacijski sustav

      1. informacijskisustav
      2. informacijskisustav_dozvole
      3. informacijskisustav_kljucnerijeci
      4. informacijskisustav_preporuke
      5. informacijskisustav_dostupnozaustanove

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

    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_osoba_vrstaulogeosobe
      19. katalog_ustanova_vrstaustrojstvenejedinice
      20. katalog_student_vrstazabrane
      21. katalog_student_razinapravanaprehranu
      22. katalog_student_razlogprestankaprava
      23. katalog_student_razlogzabrane
      24. katalog_student_vrstaposebnogstatusa
      25. katalog_upisgodine_razlogprekidastudija
      26. katalog_upisgodine_razlogpromjeneskolarine
      27. katalog_upisgodine_razlogneracunanjaponavljanja
      28. katalog_upisgodine_temeljfinanciranja
      29. katalog_upisgodine_statusupisanogpredmeta
      30. katalog_upisgodine_indikatorupisa
      31. katalog_upisgodine_nacinevidencijeupisnoglista
      32. katalog_upisgodine_nacinunosapredmeta
      33. katalog_upisgodine_nacinupisapredmeta
      34. katalog_upisgodine_nacinplacanja
      35. katalog_upisgodine_polozajuzanimanju
      36. katalog_upisgodine_postignutoobrazovanje
      37. katalog_upisgodine_uzdrzavatelj
      38. katalog_upisgodine_zanimanje
      39. katalog_upisgodine_zdravstvenoosiguranje
      40. katalog_upisgodine_statusstanovanja
      41. katalog_pds_kategorijaobveze
      42. katalog_pds_vrstazavrsetkastudija
      43. katalog_pds_vrstazavrsnograda
      44. katalog_anketa_objektprocjeneankete
      45. katalog_anketa_tipelementizvjestajaankete
      46. katalog_zavrsetakstudija_vrstateme
      47. katalog_zavrsetakstudija_vrstadanazarad
      48. katalog_zavrsetakstudija_pohvala
      49. katalog_zavrsetakstudija_vrstadokumenta
      50. katalog_strucnasprema
      51. katalog_jezik
      52. katalog_jezici
      53. katalog_skole
      54. katalog_skola
      55. katalog_nacionalnost
      56. katalog_strukovnopodrucje
      57. katalog_programizobrazbe
      58. katalog_programmobilnosti
      59. katalog_razlogdirektnogupisa
      60. katalog_vrstaliste
      61. katalog_ustrojstvenejedinice
      62. katalog_ustrojstvenajedinica
      63. katalog_mjesto
      64. katalog_drzava
      65. katalog_iscedpolje (lipanj 2023.)