docs: Update V3 api docs
This commit is contained in:
@@ -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).
|
||||
|
||||
<details>
|
||||
<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
|
||||
{
|
||||
"schedule": { /* objekt denních rozvrhů */ },
|
||||
"status": { /* objekt stavu */ }
|
||||
"status": { /* objekt stavu a metadat */ }
|
||||
}
|
||||
```
|
||||
</details>
|
||||
@@ -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
|
||||
</details>
|
||||
|
||||
##### `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.
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklady absencí</summary>
|
||||
@@ -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).
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklad status</summary>
|
||||
|
||||
Reference in New Issue
Block a user