Različice API-ja in politika LTS

Shema različic

qr3.app uporablja različice na podlagi URL-ja: /v1/, /v2/ itd.

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

Trenutna stabilna različica je v1 LTS .

Življenjski cikel različic

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

Različica	Status	Podpora do	Opombe
v1	✅ Stable (LTS)	Najmanj marec 2027	Trenutna produkcijska različica
v2	📋 Planirano	—	Roadmap: Faza 5+

Prelomne spremembe — Definicija

Prelomna sprememba (Breaking Change) je vsaka sprememba, ki onemogoči delovanje obstoječih odjemalcev brez prilagoditve:

Odstranitev ali preimenovanje polj Request/Response
Sprememba statusnih kod HTTP za obstoječe scenarije
Odstranitev končnih točk (Endpoints)
Sprememba metode avtentikacije
Nezdružljive spremembe formata napak

Niso prelomne spremembe (združljive razširitve):

Dodajanje neobveznih polj Request
Dodajanje novih polj Response
Nove končne točke (Endpoints)
Novi neobvezni poizvedovalni parametri (Query-Parameter)
Nove kode napak (RFC 7807 ostaja združljiv)

Sporočanje prelomnih sprememb

Prelomne spremembe se nikoli ne izvedejo brez predhodne najave:

Najava: Najmanj 90 dni pred prelomno spremembo
Kanal: E-pošta vsem uporabnikom API-ja + pasica na nadzorni plošči + CHANGELOG.md
Pomoč pri migraciji: Navodila za migracijo in primeri kode
Glava Deprecation: API vrne glavi HTTP 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"

Jamstva LTS (v1)

Za trenutno različico LTS v1 velja:

Jamstvo	Obdobje
Brez prelomnih sprememb	Najmanj 12 mesecev od statusa Stable
Varnostni popravki	Za celotno obdobje trajanja LTS
Popravki napak	Za celotno obdobje trajanja LTS
Način vzdrževanja	6 mesecev po koncu LTS
Popolna podpora	Najmanj do marca 2027

Prepoznavanje različice

Vsak odziv API-ja vsebuje metapodatke o trenutni različici:

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

Končna točka GET /v1/health dodatno vrne:

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

Migracija med različicami

Ko izide nova glavna različica, ostane stara različica vzporedno aktivna najmanj 6 mesecev.

Zagotavljamo:

Celotno primerjavo (diff) vseh spremenjenih končnih točk
Samodejno orodje za migracijo (kjer je mogoče)
Osebno podporo pri migraciji za stranke paketov Business/Agency

Politika opuščanja (Deprecation) za posamezne končne točke

Posamezne končne točke so lahko označene kot opuščene (deprecated) tudi znotraj iste različice:

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 sprememb (Changelog)

Vse spremembe API-ja so dokumentirane v datoteki CHANGELOG.md v repozitoriju.

Datum	Različica	Vrsta	Opis
Marec 2026	v1.0.0	Začetna	Prva stabilna izdaja: QR-kode, preusmeritve, Auth, Billing
Marec 2026	v1.1.0	Funkcija	Batch-API, A/B-Destinations, Expiry, izvoz PDF
Marec 2026	v1.2.0	Funkcija	Organizations, Workspaces, Audit-Logs, Comments, končne točke za GDPR

Vprašanja?

Če imate vprašanja o politiki različic: [email protected]