Verzování API & LTS politika

Schéma verzování

qr3.app používá verzování založené na URL: /v1/, /v2/ atd.

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

Aktuální stabilní verze je v1 LTS .

Životní cyklus verzí

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

Verze	Stav	Podpora do	Poznámky
v1	✅ Stable (LTS)	Min. březen 2027	Aktuální produkční verze
v2	📋 Plánováno	—	Roadmap: Fáze 5+

Zpětně nekompatibilní změny (Breaking Changes) — definice

Breaking Change (zpětně nekompatibilní změna) je jakákoli změna, která naruší fungování stávajících klientů bez jejich úpravy:

Odstranění nebo přejmenování polí v požadavku (Request) nebo odpovědi (Response)
Změna stavových kódů HTTP pro stávající scénáře
Odstranění endpointů
Změna metody autentizace
Nekompatibilní změny formátu chyb

Za Breaking Changes se nepovažují (kompatibilní rozšíření):

Přidání volitelných polí do požadavku (Request)
Přidání nových polí do odpovědi (Response)
Nové endpointy
Nové volitelné parametry dotazu (Query)
Nové chybové kódy (RFC 7807 zůstává kompatibilní)

Komunikace zpětně nekompatibilních změn

Zpětně nekompatibilní změny nejsou nikdy prováděny bez předchozího upozornění:

Oznámení: Minimálně 90 dní před provedením změny
Kanál: E-mail všem uživatelům API + banner na nástěnce (Dashboard) + CHANGELOG.md
Pomoc s migrací: Průvodce migrací a ukázky kódu
Hlavičky o zastarání (Deprecation): API vrací HTTP hlavičky Deprecation a 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"

Záruky LTS (v1)

Pro aktuální verzi LTS v1 platí:

Záruka	Období
Žádné Breaking Changes	Min. 12 měsíců od dosažení stavu Stable
Bezpečnostní záplaty	Po celou dobu trvání LTS
Opravy chyb	Po celou dobu trvání LTS
Režim údržby (Maintenance)	6 měsíců po skončení LTS
Plná podpora	Minimálně do března 2027

Jak zjistit verzi

Každá odpověď API obsahuje metadata o aktuální verzi:

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

Endpoint GET /v1/health navíc vrací:

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

Migrace mezi verzemi

Při vydání nové hlavní verze zůstává stará verze aktivní souběžně po dobu minimálně 6 měsíců.

Poskytujeme:

Kompletní přehled rozdílů (diff) všech změněných endpointů
Nástroj pro automatickou migraci (pokud je to možné)
Osobní podpora při migraci pro zákazníky s tarify Business/Agency

Politika zastarávání (Deprecation) pro jednotlivé endpointy

Jednotlivé endpointy mohou být označeny jako zastaralé (deprecated) i v rámci jedné verze:

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šechny změny API jsou dokumentovány v souboru CHANGELOG.md v repozitáři.

Datum	Verze	Typ	Popis
Březen 2026	v1.0.0	Initial	První stabilní verze: QR kódy, přesměrování, Auth, Billing
Březen 2026	v1.1.0	Feature	Hromadné API (Batch-API), A/B cíle, expirace, export do PDF
Březen 2026	v1.2.0	Feature	Organizace, pracovní prostory (Workspaces), auditní záznamy (Audit-Logs), komentáře, endpointy pro GDPR

Máte dotazy?

V případě dotazů k politice verzování nás kontaktujte na: [email protected]