Datový konektor

Přehled funkcionality


I. Úvod

I.1 Použití Datového konektoru

Datový konektor je určen pro přístup aplikací třetích stran k datům v systému Bakaláři. Aplikace mohou data číst i modifikovat. Příklady aplikací, které využívají datový konektor:

  • Mobilní aplikace pro platformu Android
  • Mobilní aplikace pro platformu iOS
  • Přístupové systémy
  • Systémy zobrazující informace na informačních panelech
  • Školní portály zobrazující vybrané informace ve vlastním formátu
Datový konektor je součástí webové aplikace Bakaláři.

I.2 Licencování Datového konektoru

Využívání Datového konektoru je zpoplatněno. Externím firmám, které mají s Bakaláři podepsanou smlouvu, je zasláno uživatelské jméno a heslo, které jim umožní Datový konektor využívat.

Ve výjimečných případech lze od zpoplatnění upustit. Jedná se hlavně o případy, kdy škola vyvíjí vlastní aplikaci, která je určena pouze pro použití v rámci školy a do vývoje nejsou zapojeny žádné externí firmy. Pokud aplikaci vyvíjejí studenti (např. v rámci ročníkových prací), musí každý student získat souhlasné stanovisko školy. Je vhodné, když takové stanovisko obsahuje i klauzuli o ochraně osobních údajů a GDPR.

II. Způsob komunikace

Datový konektor je přístupný pomocí HTTP protokolu (případně HTTPS protokolu) jako služba typu REST.

V případě bezchybného zpracování dotazu vrátí konektor HTTP kód 200 (OK). Pokud dojde k chybě, vrátí konektor některý z HTTP chybových kódů společně s chybovou zprávou.

III. Security

III.1 Autentikace

Některá data jsou přístupná pouze ověřeným uživatelům. Do hlavičky dotazu doplňte pole Authorization. Použita je standardní HTTP basic authentication. Komunikace je bezstavová, pole Authorization je tedy třeba vyplnit v každém požadavku. (Příklad web klienta používajícího HTTP basic authentication v jazyce C#: zde) Pokud ověření uživatele selže, vrací se HTTP kód 401 (Unauthorized).

III.2 Autorizace

Datový konektor ověřuje, zda má uživatel přístup k požadovaným datům. Pokud tomu tak není, vrací se kód 403 (Forbidden).

IV. Zprávy

Pod pojmem zpráva uvažujeme data zaslaná v těle HTTP dotazu nebo HTTP odpovědi (HTTP message content).

Datový konektor podporuje tyto formáty:

  • XML (content-type/accept: text/xml)
  • JSON (content-type/accept: application/json)
Zprávy jsou kódovány vždy jako UTF-8.

V. Data přístupná přes konektor

V této kapitole stručně popisujeme, která data jsou dostupná přes datový konektor.

V.1 Informace bez autentikace

Přístupové body v této kapitole nevyžadují autentikaci (identitu uživatele) a jsou tak přístupné komukoliv.

  • Informace o verzi konektoru: Klient může využít dotazu na tento end-point aby si ověřil, zda je datový konektor vůbec instalovaný a dostupný, případně jaká verze interfacu je nainstalovaná.
  • Diagnostika systému: Stav (status) jednotlivých modulů.

V.2 Informace o základních entitách

V této kapitole popisujeme informace o základních objektech, které jsou společné pro většinu činností provozovaných ve škole.

  • Studenti: Osobní informace o studentech: jméno, příjmení, adresu, datum narození, atd.
  • Zaměstnanci: Osobní informace o zaměstnancích školy (většinou jsou to učitelé): jméno, příjmení, adresu, datum narození, atd.
  • Zákonní zástupci: Osobní informace o zákonných zástupcích studentů (ve většině případů jsou to rodiče): jméno, příjmení, email, vztah k žákovi.
  • Budovy: Informace o školních budovách (zkratku, název, ...)
  • Místnosti: Informace o školních místnostech (většinou jsou to učebny).
  • Třídy: Informace o třídách (název, zkratka, třídní učitel, ...)

V.3 Přístupové systémy

Tato kapitola popisuje přístupové body pro práci s daty přístupových systémů (systémů evidujících příchody a odchody do/z budov/učeben a podobně).

  • Přístupové brány: Informace o jednotlivých přístupových branách.
  • Přítomnost studenta: Informace o časových úsecích (většinou vyučovacích hodinách), ve kterých by měl student být přítomen ve škole.
  • Přítomnost všech studentů: Informace o časových úsecích (většinou vyučovacích hodinách), ve kterých by měli být jednotliví studenti přítomni ve škole.
  • Přítomnost studentů v místnostech: Informace o místnostech, ve kterých by se studenti měli v časových úsecích (většinou vyučovacích hodinách) vyskytovat.
  • Vytvoření nového záznamu o průchodu: Vytvoří nový záznam o průchodu osoby.

V.4 Akce

  • Veřejné akce: Seznam akcí pořádaných školou, které může vidět volně veřejnost bez přihlášení do Bakalářů.

V.5 Rozvrh

Tato kapitola popisuje přístupové body pro získávání informací o rozvrhu.

  • Parametry rozvrhu: Vrací parametry rozvrhu (označení hodin, začátky a konce vyučovacích hodin, …)
  • Stálý rozvrh třídy: Informace o stálém rozvrhu vybrané třídy (bez suplování a jiných změn).
  • Stálý rozvrh učitele: Informace o stálém rozvrhu vybraného učitele (bez suplování a jiných změn).
  • Stálý rozvrh místnosti: Informace o stálém rozvrhu vybrané místnosti (bez suplování a jiných změn).
  • Stálý rozvrh všech tříd: Informace o stálých rozvrhzích všech tříd (bez suplování a jiných změn).
  • Aktuální rozvrh třídy: Informace o aktuálním rozvrhu vybrané třídy (včetně suplování a jiných změn) pro dnešní den.
  • Aktuální rozvrh učitele: Informace o aktuálním rozvrhu vybraného učitele (včetně suplování a jiných změn) pro dnešní den.
  • Aktuální rozvrh místnosti: Informace o aktuálním rozvrhu vybrané místnosti (včetně suplování a jiných změn) pro dnešní den.
  • Aktuální rozvrh všech tříd: Informace o aktuálních rozvrhích všech tříd (včetně suplování a jiných změn) pro dnešní den.

V.6 Suplování

  • Veřejné suplování: Informace o suplování pro daný den (podobně jako volný modul pro suplování).

V.7 Průběžná klasifikace pro učitele

  • Úvazky: Vrací úvazky, pro které může učitel zapisovat známky.
  • Známkovací arch: Informace o známkovacím archu pro daný úvazek (hlavičky sloupců pro zápis známek, seznam studentů, zapsané známky a paleta možných známek).
  • Zápis nové známky: Vytvoří a uloží novou známku.