From d638d67bec1876b4cae2406d6f8501730a83f2a7 Mon Sep 17 00:00:00 2001 From: wolfycz1 <194477237+wolfycz1@users.noreply.github.com> Date: Tue, 17 Mar 2026 15:19:44 +0100 Subject: [PATCH] docs: Update V3 api docs --- web/content/posts/api/v3/index.md | 114 +++++++++++++++++------------- 1 file changed, 66 insertions(+), 48 deletions(-) diff --git a/web/content/posts/api/v3/index.md b/web/content/posts/api/v3/index.md index 9d75f4f..811117f 100644 --- a/web/content/posts/api/v3/index.md +++ b/web/content/posts/api/v3/index.md @@ -1,19 +1,19 @@ --- -title: "API Dokumentace - Verze 2" -date: 2026-01-28 -tags: ["api", "docs", "v2"] +title: "API Dokumentace - Verze 3" +date: 2026-03-17 +tags: ["api", "docs", "v3"] hiddenInHomelist: true --- -Tato stránka detailně popisuje **Verzi 2 (v2)** API Ječná Rozvrh. +Tato stránka detailně popisuje **Verzi 3 (v3)** API Ječná Rozvrh. Endpoint poskytuje strukturovaná data o suplování, absencích, událostech a rezervacích místností. ## Endpoint: `GET /versioned/v3` -Toto je hlavní endpoint, který poskytuje veškerá data o rozvrhu pro v2. +Toto je hlavní endpoint, který poskytuje veškerá aktuální data. ### Struktura Odpovědi -Odpověď je JSON objekt, který obsahuje dva hlavní klíče: `schedule` a `status`. +Odpověď je formátována jako JSON objekt obsahující dva hlavní uzly: `schedule` (samotná data rozvrhu) a `status` (metadata o rozvrhu).
Zobrazit příklad struktury odpovědi @@ -21,7 +21,7 @@ Odpověď je JSON objekt, který obsahuje dva hlavní klíče: `schedule` a `sta ```json { "schedule": { /* objekt denních rozvrhů */ }, - "status": { /* objekt stavu */ } + "status": { /* objekt stavu a metadat */ } } ```
@@ -32,23 +32,31 @@ Odpověď je JSON objekt, který obsahuje dva hlavní klíče: `schedule` a `sta #### Sekce: `schedule` -Tato sekce je objekt, kde každý klíč představuje datum ve formátu `YYYY-MM-DD` a prvek představuje jeden den. Každý den je objekt, jehož klíče jsou `info`, `changes`, `absence`, `takesPlace` a `reservedRooms` +Tato sekce je objekt, kde každý klíč představuje datum ve formátu `YYYY-MM-DD` (např. `"2026-03-17"`). Hodnotou je objekt reprezentující data pro daný den. Tento objekt obsahuje klíče: `info`, `changes`, `absence`, `takesPlace` a `reservedRooms`. + +##### `info` + +Objekt obsahující dodatečné informace o stavu rozvrhu pro daný den. + + - `inWork` (boolean): Nabyde hodnoty `true`, pokud se s daným dnem ze strany školy ještě manipuluje (tzv. "příprava"). Znamená to, že data pro tento den **nemusí být finální** a mohou se ještě měnit. ##### `changes` -- Objekt -- **Klíč:** Název třídy (např. `"A1"`) -- **Hodnota:** Pole s 10 prvky, které reprezentují 10 vyučovacích hodin. - - Objekt: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně. - - `null`: Pokud pro ni není záznam. -Hodnota je následující objekt +Objekt obsahující změny v rozvrhu pro jednotlivé třídy. + + - **Klíč:** Název třídy (např. `"A1"`, `"C4a"`). + - **Hodnota:** Pole o **přesně 10 prvcích**, které reprezentují 1. až 10. vyučovací hodinu. + - `null`: Pro danou hodinu není evidována žádná změna (výuka probíhá normálně, nebo hodina není v rozvrhu). + - `Objekt`: Záznam o změně nebo specifické informaci. + +Struktura objektu změny: ```ts { - text: string, - backgroundColor?: string, - foregroundColor?: string, - willBeSpecified?: boolean + text: string, // Textový obsah změny (např. "M 5 odpadá") + backgroundColor: string | null, // HEX kód barvy pozadí (např. "#DCEDD5") + foregroundColor?: string, // Volitelný HEX kód barvy textu (např. "#FF000000") + willBeSpecified?: boolean // True, pokud buňka značí "bude upřesněno" (obvykle žlutá barva) } ``` @@ -58,7 +66,9 @@ Hodnota je následující objekt ```json "A1": [ { - "text": "M 5 Kp(Ng)" + "text": "M 5 Kp(Ng)", + "backgroundColor": "#FFCCCC", + "foregroundColor": "#FF000000" }, null, null, @@ -78,20 +88,26 @@ Hodnota je následující objekt ##### `absence` -- Pole objektů, kde každý objekt specifikuje jednu absenci. Struktura objektu je následující: - - `teacher` (string | null): Celé jméno učitele, pokud je známé. - - `teacherCode` (string | null): Zkratka jména učitele (např. "me", "ad"). - - `type` (string): Typ absence. Může nabývat následujících hodnot: + +Pole objektů, kde každý objekt specifikuje jednu evidovanou absenci učitele nebo změnu jeho stavu (např. exkurze). Pokud pro daný den nikdo nechybí, pole je prázdné `[]`. + +Struktura objektu absence: + + - `teacher` (string | null): Celé jméno učitele (např. `"Ing. Jan Novák"`), pokud je známé. + - `teacherCode` (string | null): Interní dvoupísmenná zkratka učitele malými písmeny (např. `"no"`). + - `type` (string): Typ záznamu. Možné hodnoty: - `"wholeDay"`: Učitel chybí celý den. - - `"single"`: Učitel chybí jednu vyučovací hodinu. - - `"range"`: Učitel chybí v rozmezí několika hodin. - - `"exkurze"`: Učitel je na exkurzi. + - `"single"`: Učitel chybí jednu konkrétní vyučovací hodinu. + - `"range"`: Učitel chybí v rozmezí několika vyučovacích hodin. + - `"exkurze"`: Učitel je mimo školu na exkurzi. + - `"zastoupen"`: Specifický stav, kdy učitele kompletně zastupuje někdo jiný. - `"invalid"`: Záznam o absenci se nepodařilo zpracovat. - - `hours` (object | number | null): Specifikuje hodiny absence. - - `null`: Pro typy `wholeDay`, `exkurze`, a `invalid`. - - `number` (např. `3`): Pro typ `single`. - - `object` (např. `{ "from": 2, "to": 4 }`): Pro typ `range`. - - `original` (string | null): Pouze pro typ `invalid`, obsahuje původní nezpracovaný text. + - `hours` (object | number | null): Specifikuje vyučovací hodiny, kterých se záznam týká. + - `null`: Pro typy `wholeDay`, `zastoupen`, `invalid` a často i `exkurze` (pokud je na celý den). + - `number` (např. `3`): Pro typ `single` (týká se pouze 3. hodiny). + - `object` (např. `{ "from": 2, "to": 4 }`): Pro typ `range` nebo částečnou `exkurze` (týká se času od 2. do 4. hodiny). + - `zastupuje` (object | volitelné): Přítomno **pouze** u typu `"zastoupen"`. Obsahuje vnořené klíče `teacher` a `teacherCode` pro učitele, který přebírá výuku. + - `original` (string | volitelné): Přítomno **pouze** u typu `"invalid"`. Obsahuje původní textový řetězec, který se nepodařilo zpracovat.
Zobrazit příklady absencí @@ -116,27 +132,27 @@ Hodnota je následující objekt } ``` -**Rozsah hodin:** +**Rozsah hodin (od-do):** ```json { - "teacher": "Jan Novák", - "teacherCode": "no", + "teacher": "Petr Svoboda", + "teacherCode": "sv", "type": "range", "hours": { "from": 2, "to": 4 } } ``` -**Exkurze:** +**Exkurze: (celý den)** ```json { - "teacher": "Jan Novák", - "teacherCode": "no", + "teacher": "Bc. Jakub Dvořák", + "teacherCode": "dv", "type": "exkurze", "hours": null } ``` -**Zastupuje:** +**Kompletní zastoupení:** ```json { "teacher": "Ing. Zdeněk Vondra", @@ -145,9 +161,9 @@ Hodnota je následující objekt "hours": null, "zastupuje": { "teacher": "David Janoušek", - "teacherCode": "jk", - }, -}, + "teacherCode": "jk" + } +} ``` **Neplatný záznam:** @@ -164,22 +180,24 @@ Hodnota je následující objekt ##### `takesPlace` -String obsahující aktuálně probíhající akce ten den. +String obsahující text aktuálně probíhajících akcí pro daný den (např. akce, exkurze, maturitní zkoušky). -#### `reservedRooms` + - Může obsahovat znaky nového řádku `\n` pro oddělení více akcí. + - Pokud pro daný den žádná akce neprobíhá, vrací prázdný string `""`. -Pole 10 prvků (string | null) pro jakou hodinu jsou rezervované jaké místnosti. +##### `reservedRooms` -#### `info.inWork` +Pole o **přesně 10 prvcích**, které reprezentuje rezervace konkrétních místností pro 1. až 10. vyučovací hodinu. -Boolean jestli je daná tabulka in work (příprava). + - `string`: Název rezervované místnosti (např. `"19a"`, `"TV"`). + - `null`: Pokud pro danou hodinu není evidována žádná rezervace místnosti. #### Sekce: `status` - Stav a Metadata Objekt poskytující informace o aktuálnosti dat. -- `lastUpdated` (string): Čas poslední úspěšné aktualizace dat ve formátu `HH:MM`. -- `currentUpdateSchedule` (number): Interval v **minutách**, ve kterém scraper interně kontroluje a stahuje novou verzi rozvrhu. Tento interval se dynamicky mění v závislosti na denní době (kratší během vyučování, delší v noci). + - `lastUpdated` (string): Čas (ve formátu `HH:MM`), kdy byla data naposledy úspěšně získána a uložena na serveru. + - `currentUpdateSchedule` (number | volitelné): Interval v minutách, ve kterém systém periodicky kontroluje nová data (může se měnit v závislosti na denní době - kratší během vyučování, delší v noci).
Zobrazit příklad status