jzitnik/jecnarozvrh
1
0
Fork 0
Code Actions Activity

docs: Update V3 api docs

Browse Source
This commit is contained in:
wolfycz1
2026-03-17 15:19:44 +01:00
committed by jzitnik-dev
parent d8713a5676
commit d638d67bec
1 changed files with 66 additions and 48 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
web/content/posts/api/v3/index.md
View File

@@ -1,19 +1,19 @@
--- ---
title: "API Dokumentace - Verze 2" title: "API Dokumentace - Verze 3"
date: 2026-01-28 date: 2026-03-17
tags: ["api", "docs", "v2"] tags: ["api", "docs", "v3"]
hiddenInHomelist: true 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` ## 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 ### 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).
<details> <details>
<summary>Zobrazit příklad struktury odpovědi</summary> <summary>Zobrazit příklad struktury odpovědi</summary>
@@ -21,7 +21,7 @@ Odpověď je JSON objekt, který obsahuje dva hlavní klíče: `schedule` a `sta
```json ```json
{ {
"schedule": { /* objekt denních rozvrhů */ }, "schedule": { /* objekt denních rozvrhů */ },
"status": { /* objekt stavu */ } "status": { /* objekt stavu a metadat */ }
} }
``` ```
</details> </details>
@@ -32,23 +32,31 @@ Odpověď je JSON objekt, který obsahuje dva hlavní klíče: `schedule` a `sta
#### Sekce: `schedule` #### 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` ##### `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 ```ts
{ {
text: string, text: string, // Textový obsah změny (např. "M 5 odpadá")
backgroundColor?: string, backgroundColor: string | null, // HEX kód barvy pozadí (např. "#DCEDD5")
foregroundColor?: string, foregroundColor?: string, // Volitelný HEX kód barvy textu (např. "#FF000000")
willBeSpecified?: boolean 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 ```json
"A1": [ "A1": [
{ {
"text": "M 5 Kp(Ng)" "text": "M 5 Kp(Ng)",
"backgroundColor": "#FFCCCC",
"foregroundColor": "#FF000000"
}, },
null, null,
null, null,
@@ -78,20 +88,26 @@ Hodnota je následující objekt
</details> </details>
##### `absence` ##### `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é. 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é `[]`.
- `teacherCode` (string | null): Zkratka jména učitele (např. "me", "ad").
- `type` (string): Typ absence. Může nabývat následujících hodnot: 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. - `"wholeDay"`: Učitel chybí celý den.
- `"single"`: Učitel chybí jednu vyučovací hodinu. - `"single"`: Učitel chybí jednu konkrétní vyučovací hodinu.
- `"range"`: Učitel chybí v rozmezí několika hodin. - `"range"`: Učitel chybí v rozmezí několika vyučovacích hodin.
- `"exkurze"`: Učitel je na exkurzi. - `"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. - `"invalid"`: Záznam o absenci se nepodařilo zpracovat.
- `hours` (object | number | null): Specifikuje hodiny absence. - `hours` (object | number | null): Specifikuje vyučovací hodiny, kterých se záznam týká.
- `null`: Pro typy `wholeDay`, `exkurze`, a `invalid`. - `null`: Pro typy `wholeDay`, `zastoupen`, `invalid` a často i `exkurze` (pokud je na celý den).
- `number` (např. `3`): Pro typ `single`. - `number` (např. `3`): Pro typ `single` (týká se pouze 3. hodiny).
- `object` (např. `{ "from": 2, "to": 4 }`): Pro typ `range`. - `object` (např. `{ "from": 2, "to": 4 }`): Pro typ `range` nebo částečnou `exkurze` (týká se času od 2. do 4. hodiny).
- `original` (string | null): Pouze pro typ `invalid`, obsahuje původní nezpracovaný text. - `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.
<details> <details>
<summary>Zobrazit příklady absencí</summary> <summary>Zobrazit příklady absencí</summary>
@@ -116,27 +132,27 @@ Hodnota je následující objekt
} }
``` ```
**Rozsah hodin:** **Rozsah hodin (od-do):**
```json ```json
{ {
"teacher": "Jan Novák", "teacher": "Petr Svoboda",
"teacherCode": "no", "teacherCode": "sv",
"type": "range", "type": "range",
"hours": { "from": 2, "to": 4 } "hours": { "from": 2, "to": 4 }
} }
``` ```
**Exkurze:** **Exkurze: (celý den)**
```json ```json
{ {
"teacher": "Jan Novák", "teacher": "Bc. Jakub Dvořák",
"teacherCode": "no", "teacherCode": "dv",
"type": "exkurze", "type": "exkurze",
"hours": null "hours": null
} }
``` ```
**Zastupuje:** **Kompletní zastoupení:**
```json ```json
{ {
"teacher": "Ing. Zdeněk Vondra", "teacher": "Ing. Zdeněk Vondra",
@@ -145,9 +161,9 @@ Hodnota je následující objekt
"hours": null, "hours": null,
"zastupuje": { "zastupuje": {
"teacher": "David Janoušek", "teacher": "David Janoušek",
"teacherCode": "jk", "teacherCode": "jk"
}, }
}, }
``` ```
**Neplatný záznam:** **Neplatný záznam:**
@@ -164,22 +180,24 @@ Hodnota je následující objekt
##### `takesPlace` ##### `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 #### Sekce: `status` - Stav a Metadata
Objekt poskytující informace o aktuálnosti dat. Objekt poskytující informace o aktuálnosti dat.
- `lastUpdated` (string): Čas poslední úspěšné aktualizace dat ve formátu `HH:MM`. - `lastUpdated` (string): Čas (ve formátu `HH:MM`), kdy byla data naposledy úspěšně získána a uložena na serveru.
- `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). - `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).
<details> <details>
<summary>Zobrazit příklad status</summary> <summary>Zobrazit příklad status</summary>