Verziovanie API & LTS politika

Schéma verziovania

qr3.app používa verziovanie založené na URL: /v1/, /v2/ atď.

https://qr3.app/v1/codes
                    ^^^
                    Versionspräfix

Aktuálna stabilná verzia je v1 LTS .

Životný cyklus verzií

Neu         → Stable (LTS) → Maintenance → End-of-Life
 Beta-Phase    Aktiv            Nur Fixes      Eingestellt
 (0–3 Monate)  (12+ Monate)     (6 Monate)     (danach)

Verzia	Stav	Podpora do	Poznámky
v1	✅ Stable (LTS)	Min. marec 2027	Aktuálna produkčná verzia
v2	📋 Plánované	—	Roadmap: Fáza 5+

Prelomové zmeny (Breaking Changes) — Definícia

Prelomová zmena (Breaking Change) je akákoľvek zmena, ktorá znefunkční existujúcich klientov bez ich úpravy:

Odstránenie alebo premenovanie polí požiadavky (Request) alebo odpovede (Response)
Zmena stavových kódov HTTP pre existujúce scenáre
Odstránenie endpointov
Zmena metódy autentifikácie
Nekompatibilné zmeny formátu chýb

Nie sú prelomové zmeny (kompatibilné rozšírenia):

Pridanie voliteľných polí požiadavky (Request)
Pridanie nových polí odpovede (Response)
Nové endpointy
Nové voliteľné parametre dopytu (Query)
Nové chybové kódy (RFC 7807 zostáva kompatibilný)

Komunikácia prelomových zmien

Prelomové zmeny sa nikdy neuskutočňujú bez oznámenia:

Oznámenie: Minimálne 90 dní pred prelomovou zmenou
Kanál: E-mail všetkým používateľom API + banner na nástenke (Dashboard) + CHANGELOG.md
Pomoc s migráciou: Návod na migráciu a ukážky kódu
Hlavičky o zastaraní (Deprecation): API poskytuje HTTP hlavičky Deprecation + Sunset

HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.qr3.app/de/api/versioning>; rel="deprecation"

LTS záruky (v1)

Pre aktuálnu verziu LTS v1 platí:

Záruka	Obdobie
Žiadne prelomové zmeny	Min. 12 mesiacov od stavu Stable
Bezpečnostné záplaty	Počas celej doby podpory LTS
Opravy chýb	Počas celej doby podpory LTS
Režim údržby (Maintenance Mode)	6 mesiacov po skončení LTS
Úplná podpora	Min. do marca 2027

Identifikácia verzie

Každá odpoveď API obsahuje metadáta o aktuálnej verzii:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "api_version": "1.0.0"
  }
}

Endpoint GET /v1/health navyše poskytuje:

{
  "version": "1.0.0",
  "environment": "production",
  "status": "ok"
}

Migrácia medzi verziami

Keď vyjde nová hlavná verzia, stará verzia zostáva aktívna súbežne minimálne 6 mesiacov.

Poskytujeme:

Úplný rozdiel (diff) všetkých zmenených endpointov
Automatický migračný nástroj (ak je to možné)
Osobnú podporu pri migrácii pre zákazníkov s programom Business/Agency

Politika zastarávania (Deprecation Policy) pre jednotlivé endpointy

Jednotlivé endpointy môžu byť označené ako zastarané (deprecated) aj v rámci jednej verzie:

GET /v1/codes HTTP/1.1

HTTP/1.1 200 OK
Deprecation: true
Sunset: Thu, 01 Jan 2026 00:00:00 GMT
Link: <https://docs.qr3.app/de/api/codes>; rel="deprecation"

Changelog

Všetky zmeny API sú zdokumentované v súbore CHANGELOG.md v repozitári.

Dátum	Verzia	Typ	Popis
Marec 2026	v1.0.0	Initial	Prvé stabilné vydanie: QR kódy, presmerovanie, Auth, Billing
Marec 2026	v1.1.0	Feature	Batch API, A/B destinácie, Expiry, export do PDF
Marec 2026	v1.2.0	Feature	Organizations, Workspaces, Audit-Logs, Comments, GDPR endpointy

Otázky?

V prípade otázok k politike verziovania: [email protected]