Upravljanje verzijama API-ja i LTS pravila

Shema upravljanja verzijama

qr3.app koristi upravljanje verzijama temeljeno na URL-u: /v1/, /v2/ itd.

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

Trenutna stabilna verzija je v1 LTS .

Životni ciklus verzije

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

Verzija	Status	Podrška do	Napomene
v1	✅ Stable (LTS)	Najmanje ožujak 2027.	Trenutna produkcijska verzija
v2	📋 Planirano	—	Plan puta: Faza 5+

Prijelomne promjene (Breaking Changes) — Definicija

Prijelomna promjena (Breaking Change) je svaka promjena koja kvari postojeće klijente bez prilagodbe:

Uklanjanje ili preimenovanje polja zahtjeva/odgovora (Request/Response)
Promjena HTTP statusnih kodova za postojeće scenarije
Uklanjanje krajnjih točaka (Endpoints)
Promjena metode autentifikacije
Nekompatibilne promjene formata pogreške

Nisu prijelomne promjene (kompatibilna proširenja):

Dodavanje neobaveznih polja zahtjeva (Request)
Dodavanje novih polja odgovora (Response)
Nove krajnje točke (Endpoints)
Novi neobavezni parametri upita (Query)
Novi kodovi pogrešaka (RFC 7807 ostaje kompatibilan)

Komunikacija prijelomnih promjena

Prijelomne promjene se nikada ne provode bez najave:

Najava: Najmanje 90 dana prije prijelomne promjene
Kanal: E-pošta svim korisnicima API-ja + banner na nadzornoj ploči + CHANGELOG.md
Pomoć pri migraciji: Vodič za migraciju i primjeri koda
Zaglavlja zastarjelosti (Deprecation): API isporučuje Deprecation + Sunset HTTP zaglavlja

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

Za trenutnu LTS verziju v1 vrijedi:

Jamstvo	Razdoblje
Bez prijelomnih promjena	Najmanje 12 mjeseci od stabilnog statusa
Sigurnosne zakrpe (Security Patches)	Tijekom cijelog trajanja LTS-a
Ispravci pogrešaka (Bug Fixes)	Tijekom cijelog trajanja LTS-a
Način održavanja (Maintenance Mode)	6 mjeseci nakon završetka LTS-a
Potpuna podrška	Najmanje do ožujka 2027.

Prepoznavanje verzije

Svaki API odgovor (Response) sadrži metapodatke o trenutnoj verziji:

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

Krajnja točka GET /v1/health dodatno isporučuje:

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

Migracija između verzija

Kada se pojavi nova glavna verzija, stara verzija ostaje aktivna paralelno najmanje 6 mjeseci.

Nudimo:

Potpuni prikaz razlika (Diff) svih izmijenjenih krajnjih točaka
Automatski alat za migraciju (gdje je moguće)
Osobna podrška pri migraciji za Business/Agency korisnike

Pravila o zastarjelosti (Deprecation Policy) za pojedinačne krajnje točke

Pojedinačne krajnje točke mogu se označiti kao zastarjele (deprecated) čak i unutar jedne verzije:

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"

Dnevnik promjena (Changelog)

Sve promjene API-ja dokumentirane su u datoteci CHANGELOG.md u repozitoriju.

Datum	Verzija	Vrsta	Opis
Ožujak 2026.	v1.0.0	Početno	Prvo stabilno izdanje: QR kodovi, preusmjeravanje, Auth, naplata (Billing)
Ožujak 2026.	v1.1.0	Značajka	Batch-API, A/B odredišta, istek (Expiry), PDF izvoz
Ožujak 2026.	v1.2.0	Značajka	Organizacije, radni prostori (Workspaces), zapisi revizije (Audit-Logs), komentari, GDPR krajnje točke

Pitanja?

Za pitanja o pravilima upravljanja verzijama: [email protected]