This commit is contained in:
235
web/content/posts/api-usage-v1/index.md
Normal file
235
web/content/posts/api-usage-v1/index.md
Normal file
@@ -0,0 +1,235 @@
|
||||
---
|
||||
title: "API Dokumentace - Verze 1"
|
||||
date: 2025-12-20
|
||||
tags: ["api", "docs", "v1"]
|
||||
hiddenInHomelist: true
|
||||
---
|
||||
|
||||
Tato stránka detailně popisuje **Verzi 1 (v1)** API Ječná Rozvrh.
|
||||
|
||||
## Endpoint: `GET /versioned/v1`
|
||||
|
||||
Toto je hlavní endpoint, který poskytuje veškerá data o rozvrhu pro v1.
|
||||
|
||||
### Struktura Odpovědi
|
||||
|
||||
Odpověď je JSON objekt, který obsahuje tři hlavní klíče: `schedule`, `props`, a `status`.
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklad struktury odpovědi</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"schedule": [ /* pole denních rozvrhů */ ],
|
||||
"props": [ /* pole vlastností dnů */ ],
|
||||
"status": { /* objekt stavu */ }
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
### Datové Struktury
|
||||
|
||||
#### Sekce: `schedule`
|
||||
|
||||
Tato sekce je pole, kde každý prvek představuje jeden den. Každý den je objekt, jehož klíče jsou názvy jednotlivých tříd (např. `A1`, `C2a`, `E4`) a speciální klíč `ABSENCE`.
|
||||
|
||||
##### Rozvrh Třídy
|
||||
- **Klíč:** Název třídy (např. `"A1"`)
|
||||
- **Hodnota:** Pole s 10 prvky, které reprezentují 10 vyučovacích hodin.
|
||||
- `string`: Pokud je hodina normálně vyučována, obsahuje název předmětu nebo informaci o změně.
|
||||
- `null`: Pokud hodina odpadá nebo pro ni není záznam.
|
||||
- Text `(bude upřesněno)` může být připojen k předmětu, pokud je změna nejistá.
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklad rozvrhu pro třídu A1</summary>
|
||||
|
||||
```json
|
||||
"A1": [
|
||||
"M 5 Kp(Ng)",
|
||||
null,
|
||||
null,
|
||||
"(Me) (bude upřesněno)",
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null
|
||||
]
|
||||
```
|
||||
</details>
|
||||
|
||||
##### Absence Učitelů
|
||||
- **Klíč:** `"ABSENCE"`
|
||||
- **Hodnota:** 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:
|
||||
- `"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.
|
||||
- `"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.
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklady absencí</summary>
|
||||
|
||||
**Celý den:**
|
||||
```json
|
||||
{
|
||||
"teacher": "Jan Novák",
|
||||
"teacherCode": "no",
|
||||
"type": "wholeDay",
|
||||
"hours": null
|
||||
}
|
||||
```
|
||||
|
||||
**Jedna hodina:**
|
||||
```json
|
||||
{
|
||||
"teacher": "Jan Novák",
|
||||
"teacherCode": "no",
|
||||
"type": "single",
|
||||
"hours": 1
|
||||
}
|
||||
```
|
||||
|
||||
**Rozsah hodin:**
|
||||
```json
|
||||
{
|
||||
"teacher": "Jan Novák",
|
||||
"teacherCode": "no",
|
||||
"type": "range",
|
||||
"hours": { "from": 2, "to": 4 }
|
||||
}
|
||||
```
|
||||
|
||||
**Exkurze:**
|
||||
```json
|
||||
{
|
||||
"teacher": "Jan Novák",
|
||||
"teacherCode": "no",
|
||||
"type": "exkurze",
|
||||
"hours": null
|
||||
}
|
||||
```
|
||||
|
||||
**Neplatný záznam:**
|
||||
```json
|
||||
{
|
||||
"type": "invalid",
|
||||
"teacher": null,
|
||||
"teacherCode": null,
|
||||
"hours": null,
|
||||
"original": "Nezpracovatelný text"
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
#### Sekce: `props` - Vlastnosti Dnů
|
||||
|
||||
Pole objektů, které doplňují metadata ke každému dni v poli `schedule`. Pořadí prvků v `props` přesně odpovídá pořadí dnů v `schedule`.
|
||||
|
||||
- `date` (string): Datum daného rozvrhu ve formátu `YYYY-MM-DD`.
|
||||
- `priprava` (boolean): Hodnota je `true`, pokud je den součástí "přípravného týdne", jinak `false`.
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklad props</summary>
|
||||
|
||||
```json
|
||||
"props": [
|
||||
{
|
||||
"date": "2025-12-20",
|
||||
"priprava": false
|
||||
},
|
||||
{
|
||||
"date": "2025-12-21",
|
||||
"priprava": true
|
||||
}
|
||||
]
|
||||
```
|
||||
</details>
|
||||
|
||||
#### 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).
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit příklad status</summary>
|
||||
|
||||
```json
|
||||
"status": {
|
||||
"lastUpdated": "08:30",
|
||||
"currentUpdateSchedule": 5
|
||||
}
|
||||
```
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
### Kompletní Příklad Odpovědi z `GET /versioned/v1`
|
||||
|
||||
<details>
|
||||
<summary>Zobrazit kompletní příklad</summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"schedule": [
|
||||
{
|
||||
"A1": [
|
||||
"M 6 Kp(Ng)",
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
"(Me) (bude upřesněno)",
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null
|
||||
],
|
||||
"C2": [
|
||||
"M 6 Kp(Ng)",
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
"(Me) (bude upřesněno)",
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null,
|
||||
null
|
||||
],
|
||||
"ABSENCE": [
|
||||
{
|
||||
"teacher": "Jan Novák",
|
||||
"teacherCode": "no",
|
||||
"type": "range",
|
||||
"hours": {"from": 1, "to": 3}
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"props": [
|
||||
{
|
||||
"date": "2025-12-20",
|
||||
"priprava": false
|
||||
}
|
||||
],
|
||||
"status": {
|
||||
"lastUpdated": "14:30",
|
||||
"currentUpdateSchedule": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
</details>
|
||||
Reference in New Issue
Block a user