jecnarozvrh/web/content/posts/api-usage/v1.md

---
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>