REST API pro export dat

Z rozvrhu je možné exportovat data ve strojově čitelném formátu JSON. Pro export slouží rozhraní reprezentované skriptem rest.php v kořenu modulu rozvrhng.

Toto rozhraní obsluhuje řadu endpointů, což jsou nezávislé služby poskytující data (např. endpoint muj_rozvrh). Rozhraní nepoužívá klasické přihlášení uživatele, ale je zabezpečeno konfiguračním parametrem bezpecnostni_tokeny modulu RozvrhNG, který může obsahovat jeden nebo i více tajných řetězců používaných pro autentizaci uživatelů (viz dále).

Dotazy na toto rozhraní se provádí metodou GET, potřebné parametry se nachází v URL query. Všechny dotazy musí povinně obshahovat parametry:

Každý endpoint může požadovat další parametry, které ovlivňují, co bude obsahem odpovědi. Korektní odpovědi vrací vždy HTTP kód 200 a tělo odpovídající JSON dokumentu. Chybné odpovědi vrací příslušný HTTP kód (typicky 400, pokud jsou parametry v nepořádku) a textovou chybovou hlášku.

Zabezpečení proti zneužití je zajištěno tajným řetězcem, který administrátor nastaví do konfiguračního parametru bezpecnostni_tokeny a sdělí ho uživateli tohoto rozhraní. Konfigurační parametr bezpecnostni_tokeny může obsahovat více tajných řetězců, které jsou od sebe odděleny znakem středník ';' a k ověření je možné použít libovolný z těchto řetězců. Administrátor tak může přidělit různé tajné řetězce různým uživatelům. Je doporučeno používat v řetězcích pouze alfanumerické a běžně používané ne-bílé znaky (@, -, _, $, ...). Tajné řetězce musí obsahovat alespoň 5 znaků, jinak jsou ignorovány. V případě používání více tajných řetězců doporučujeme doplnit ke každému z nich nějakou formu identifikace uživatele, kterému byl řetězec poskytnut, např.

prisnetajnyretezec@Pepa

Uživatel služby vygeneruje z tajného řetězce autentizační token následovně. Token se skládá ze dvou částí -- salt a hash, mezi které je vložen znak dolar '$'. Salt vznikne zřetězením tzv. salt-atributů za sebe pomocí znaku čárka ','. První a jediný povinný salt-atribut je aktuální unix timestamp (kdy je dotaz položen) zapsaný dekadicky. Další salt-atributy může volitelně vyžadovat vybraný endpoint. Hash je SHA256 kryptografický otisk řetězce, který vznikne spojením salt řetězce, čárky a tajného řetězce.

Příklad: pokud zvolený endpoint např. požaduje jako druhý salt-attribut číslo fakulty, pak bychom autentizační token symbolicky zapsali jako

<unixTS> + ',' + <fakulta> + '$' + SHA256(<unixTS> + ',' + <fakulta> + ',' + <tajny_retezec>)

Časové razítko (unix timestamp) se navíc ověřuje, zda je rozumně daleko od aktuálního času. Server akceptuje pouze časová razítka, která jsou v rozmezí plus-minus 1 hodina od aktuálního času serveru.