Politika verzí a zralost API

Co znamená stable a beta, stav kolekcí (implemented, derived-view, planned, deprecated) a jak se ohlašují změny.

API v2 · schemaVersion 2.2.0 · release m-120191 (2026-10-21T23:45:15+02:00)

Stable a beta (x-stage)

Každá operace v OpenAPI má x-stage:

x-stage	Co slibujeme
`stable`	Jádro API v2. V rámci `/api/v2` jen aditivní změny (nová pole, nové hodnoty enumů, nové parametry). Odebrání nebo změna významu pole či parametru: nejdřív `deprecated` v OpenAPI a záznam v changelogu, souběh nejméně 6 měsíců, hlavičky `Deprecation` a `Sunset`, teprve potom nová major verze nebo odebrání.
`beta`	Funkční a veřejné, ale tvar se může změnit i bez šestiměsíčního souběhu. Každá změna je v changelogu; po stabilizaci se operace přepne na `stable` (záznam v changelogu).

Jádro (stable): index /api/v2, /status a stav areálu, kolekce se stavem implemented (seznam i detail), /entities/{id}, /search, /prices, /age-categories, /releases/latest, /quality.

Pohledy v indexu: status stable · entities stable · search stable · prices stable · age-categories stable · releases-latest stable · quality stable · resort beta · weather beta · glossary beta · jsonld beta · web-llms beta · web-robots beta · web-pages beta.

Klient musí vždy ignorovat neznámá pole a tolerovat nové hodnoty enumů – to platí i pro stable.

Stav kolekcí (stage)

Index /api/v2 uvádí u každé kolekce stage (a stageNote), OpenAPI totéž jako x-collection-stage:

implemented – kolekce se plní ze zdrojů a je součástí jádra.
derived-view – entity se skládají v souhrnném pohledu; samotná kolekce může být prázdná, používejte pohled.
planned – typ je v registru, zdroj zatím není napojen (kolekce bývá prázdná).
deprecated – kolekce se ruší podle pravidel výše (zatím žádná).

Kolekce	stage	Poznámka
`skitour-routes`	planned	Typ je v registru, zdroj skialpových tras zatím není napojen.
`weather-stations`	planned	Typ je v registru; pozorování počasí jsou v /api/v2/weather.
`age-category-sets`	derived-view	Sady věkových kategorií se odvozují z ceníků v pohledu /api/v2/age-categories.
`price-lists`	derived-view	Ceníky se skládají z nabídek v pohledu /api/v2/prices.

Všechny ostatní kolekce mají implemented.

Jak se změny ohlašují

Changelog (také Markdown) – každá změna veřejného rozhraní.
meta.schemaVersion (semver datového kontraktu) a info.version v OpenAPI; minor = aditivní, major = nová cesta /api/vN.
API v1 (/api/v1/*) běží beze změny do 30. 6. 2027, viz migrace v1 → v2.

Dokumentace

Data Hub pro agentury a vývojáře – Co Data Hub obsahuje, jak číst identifikátory, stavy, čas, cache, verze a licence – s příklady volání.
API reference (OpenAPI 3.1) – Interaktivní reference veřejného API v2 generovaná z OpenAPI 3.1.
Datový slovník – Typy entit a jejich atributy z registru domény: jednotky, vrstvy, rodiny, časovost a mapování.
Číselníky – Kódy typů lanovek, obtížností, stavů, relací, důvodů, sezónních fází, kategorií služeb a druhů zdrojů.
Glosář pojmů – Pojmy resortu (SkiTour, Flexiskipas, sKiosek…) s definicemi z aktuálního releasu.
Pro AI agenty: MCP, OpenAPI a llms.txt – Read-only MCP server, nástroje, limity a jak citovat data.
Changelog – Změny produktu a schématu API v2.
Politika verzí a zralost API – Co znamená stable a beta, stav kolekcí (implemented, derived-view, planned, deprecated) a jak se ohlašují změny.
Licence a atribuce – Za jakých podmínek lze data použít a jak uvádět zdroje.
Migrace z API v1 na v2 – Mapování polí a identifikátorů v1 → v2 a harmonogram ukončení v1.