API versijų valdymas ir LTS politika

Versijų kūrimo schema

qr3.app naudoja URL pagrįstą versijų valdymą: /v1/, /v2/ ir t. t.

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

Dabartinė stabili versija yra v1 LTS .

Versijos gyvavimo ciklas

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

Versija	Būsena	Palaikymas iki	Pastabos
v1	✅ Stable (LTS)	Ne trumpiau kaip iki 2027 m. kovo mėn.	Dabartinė gamybinė versija
v2	📋 Planuojama	—	Gairės (Roadmap): 5+ etapas

Esminiai pakeitimai (Breaking Changes) — apibrėžimas

Esminis pakeitimas (Breaking Change) yra bet koks pakeitimas, kuris sugadina esamų klientų veikimą be papildomų pritaikymų:

Užklausos (Request) arba atsakymo (Response) laukų pašalinimas ar pervadinimas
HTTP būsenos kodų keitimas esamiems scenarijams
Pabaigos taškų (Endpoints) pašalinimas
Autentifikavimo metodo keitimas
Nesuderinami klaidų formato pakeitimai

Nėra esminiai pakeitimai (suderinami išplėtimai):

Neprivalomų užklausos laukų pridėjimas
Naujų atsakymo laukų pridėjimas
Nauji pabaigos taškai (Endpoints)
Nauji neprivalomi užklausos parametrai (Query parameters)
Nauji klaidų kodai (RFC 7807 išlieka suderinamas)

Pranešimas apie esminius pakeitimus

Esminiai pakeitimai niekada neatliekami be išankstinio įspėjimo:

Pranešimas: Ne vėliau kaip prieš 90 dienų iki esminio pakeitimo
Kanalas: El. laiškas visiems API naudotojams + skydelis valdymo skydelyje (Dashboard) + CHANGELOG.md
Pagalba migruojant: Migracijos gairės ir kodų pavyzdžiai
Nurašymo antraštės (Deprecation Headers): API pateikia Deprecation ir Sunset HTTP antraštes

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 garantijos (v1)

Dabartinei LTS versijai v1 taikoma:

Garantija	Laikotarpis
Jokių esminių pakeitimų	Ne trumpiau kaip 12 mėnesių nuo Stable statuso suteikimo
Saugumo pataisymai	Visą LTS galiojimo laikotarpį
Klaidų taisymai	Visą LTS galiojimo laikotarpį
Priežiūros režimas (Maintenance Mode)	6 mėnesiai po LTS pabaigos
Pilnas palaikymas	Ne trumpiau kaip iki 2027 m. kovo mėn.

Versijos atpažinimas

Kiekviename API atsakyme yra metaduomenys apie dabartinę versiją:

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

GET /v1/health pabaigos taškas papildomai pateikia:

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

Migracija tarp versijų

Kai pasirodo nauja pagrindinė versija, senoji versija išlieka aktyvi lygiagrečiai mažiausiai 6 mėnesius.

Mes pateikiame:

Išsamų visų pakeistų pabaigos taškų skirtumų (Diff) sąrašą
Automatinį migracijos įrankį (kur įmanoma)
Asmeninį palaikymą migruojant Business / Agency klientams

Atskirų pabaigos taškų (Endpoints) nurašymo politika

Atskiri pabaigos taškai gali būti pažymėti kaip nurašyti (deprecated) net ir tos pačios versijos ribose:

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"

Pakeitimų žurnalas (Changelog)

Visi API pakeitimai dokumentuojami saugyklos faile CHANGELOG.md.

Data	Versija	Tipas	Aprašymas
2026 m. kovo mėn.	v1.0.0	Pradinė	Pirmasis stabilus leidimas: QR kodai, nukreipimai (Redirect), Auth, atsiskaitymas (Billing)
2026 m. kovo mėn.	v1.1.0	Funkcija	Masinė API (Batch-API), A/B tikslai (A/B-Destinations), galiojimo laikas (Expiry), PDF eksportas
2026 m. kovo mėn.	v1.2.0	Funkcija	Organizacijos (Organizations), darbo sritys (Workspaces), audito žurnalai (Audit-Logs), komentarai, BDAR pabaigos taškai

Turite klausimų?

Kilus klausimų dėl versijų valdymo politikos: [email protected]