API-verziókezelés és LTS-irányelvek

Verziókezelési séma

qr3.app URL-alapú verziókezelést használ: /v1/, /v2/ stb.

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

A jelenlegi stabil verzió a v1 LTS .

Verziók életciklusa

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

Verzió	Állapot	Támogatás eddig	Megjegyzések
v1	✅ Stabil (LTS)	Min. 2027. március	Jelenlegi éles verzió
v2	📋 Tervezett	—	Útiterv: 5+ fázis

Breaking Changes — Meghatározás

A Breaking Change (visszafelé nem kompatibilis változtatás) minden olyan módosítás, amely a meglévő klienseket módosítás nélkül működésképtelenné teszi:

Request-/Response-mezők eltávolítása vagy átnevezése
HTTP-státuszkódok módosítása meglévő forgatókönyvek esetén
Endpointok eltávolítása
Az autentikációs módszer megváltoztatása
Nem kompatibilis változtatások a hibaformátumban

Nem számít Breaking Change-nek (kompatibilis bővítések):

Opcionális Request-mezők hozzáadása
Új Response-mezők hozzáadása
Új endpointok
Új opcionális query paraméterek
Új hibakódok (az RFC 7807 kompatibilis marad)

Breaking Changes kommunikációja

A Breaking Change-eket soha nem hajtjuk végre előzetes bejelentés nélkül:

Bejelentés: Legalább 90 nappal a Breaking Change előtt
Csatorna: E-mail minden API-felhasználónak + Dashboard banner + CHANGELOG.md
Migrációs segítség: Migrációs útmutató és kódpéldák
Deprecation-fejlécek: Az API Deprecation + Sunset HTTP-fejléceket küld

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-garanciák (v1)

A jelenlegi v1 LTS-verzióra a következők érvényesek:

Garancia	Időtartam
Nincsenek Breaking Change-ek	Min. 12 hónap a stabil állapottól számítva
Biztonsági javítások (Security Patches)	A teljes LTS-időszak alatt
Hibajavítások (Bug Fixes)	A teljes LTS-időszak alatt
Karbantartási mód (Maintenance Mode)	6 hónappal az LTS lejárta után
Teljes körű támogatás	Legalább 2027. márciusig

Verzió azonosítása

Minden API-válasz tartalmaz metaadatokat az aktuális verzióról:

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

A GET /v1/health endpoint ezen felül a következőket adja vissza:

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

Verziók közötti migráció

Új főverzió megjelenésekor a régi verzió legalább 6 hónapig párhuzamosan aktív marad.

A következőket biztosítjuk:

Az összes módosított endpoint teljes diffje (különbséglistája)
Automatikus migrációs eszköz (ahol lehéséges)
Személyes migrációs támogatás Business/Agency ügyfelek számára

Deprecation-irányelvek egyes endpointokhoz

Egyes endpointok egy adott verzión belül is megjelölhetők elavultként (deprecated):

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

Minden API-változás dokumentálva van a tárolóban található CHANGELOG.md fájlban.

Dátum	Verzió	Típus	Leírás
2026. március	v1.0.0	Kezdeti	Első stabil kiadás: QR-kódok, átirányítás (Redirect), Auth, számlázás (Billing)
2026. március	v1.1.0	Funkció	Batch-API, A/B-célállomások (A/B-Destinations), lejárati idő (Expiry), PDF-exportálás
2026. március	v1.2.0	Funkció	Szervezetek (Organizations), munkaterületek (Workspaces), audit naplók (Audit-Logs), megjegyzések (Comments), GDPR-endpointok (DSGVO-Endpoints)

Kérdése van?

A verziókezelési irányelvekkel kapcsolatos kérdések esetén: [email protected]