Versiunea API & Politica LTS

Versiunea API & Politica LTS

Schema de versiuni

qr3.app utilizează versioanare bazată pe URL: /v1/, /v2/ etc.

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

Versiunea stabilă curentă este v1 LTS .

---

Ciclul de viață al versiunilor

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

Versiune	Status	Suport până la	Note
v1	✅ Stable (LTS)	Min. martie 2027	Versiunea de producție curentă
v2	📋 Planificată	—	Roadmap: Faza 5+

---

Modificări majore (Breaking Changes) — Definiție

O modificare majoră (breaking change) este orice modificare care afectează funcționarea clienților existenți fără o adaptare prealabilă:

• Eliminarea sau redenumirea câmpurilor de Request/Response
• Modificarea codurilor de stare HTTP pentru scenariile existente
• Eliminarea endpoint-urilor
• Modificarea metodei de autentificare
• Modificări incompatibile ale formatului de eroare

Nu sunt considerate modificări majore (extensii compatibile):

• Adăugarea de câmpuri opționale de Request
• Adăugarea de noi câmpuri de Response
• Endpoint-uri noi
• Noi parametri opționali de Query
• Noi coduri de eroare (RFC 7807 rămâne compatibil)

---

Comunicarea modificărilor majore

Modificările majore nu sunt niciodată efectuate fără notificare prealabilă:

1. Anunț: Cu cel puțin 90 de zile înainte de modificarea majoră
2. Canal: E-mail către toți utilizatorii API + banner în panoul de control + CHANGELOG.md
3. Asistență pentru migrare: Ghid de migrare și exemple de cod
4. Antete de depreciere: API-ul returnează antetele HTTP Deprecation și 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"

---

Garanții LTS (v1)

Pentru versiunea LTS curentă v1 se aplică următoarele:

Garanție	Perioadă
Fără modificări majore	Min. 12 luni de la stadiul Stable
Patch-uri de securitate	Pe întreaga durată de viață LTS
Remedieri de erori (Bug Fixes)	Pe întreaga durată de viață LTS
Mod de întreținere (Maintenance Mode)	6 luni după încheierea LTS
Suport complet	Cel puțin până în martie 2027

Versiunea în SDK

SDK-ul TypeScript (@qr3/sdk) și CLI-ul (@qr3/cli) urmează, de asemenea, SemVer. Modificările majore din SDK reflectă întotdeauna modificările majore din API.

---

Identificarea versiunii

Fiecare răspuns API conține metadate despre versiunea curentă:

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

Endpoint-ul GET /v1/health returnează în plus:

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

---

Migrarea între versiuni

Atunci când apare o nouă versiune majoră, versiunea veche rămâne activă în paralel timp de cel puțin 6 luni.

Noi oferim:

• Un diff complet al tuturor endpoint-urilor modificate
• Instrument de migrare automată (acolo unde este posibil)
• Suport personalizat pentru migrare pentru clienții Business/Agency

---

Politica de depreciere pentru endpoint-uri individuale

Endpoint-urile individuale pot fi marcate ca depreciate chiar și în cadrul aceleiași versiuni:

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"

Atenție

Nu ignorați antetele Deprecation. Endpoint-urile vor fi eliminate după data specificată în Sunset, chiar dacă nu au reprezentat încă o modificare majoră.

---

Jurnal de modificări (Changelog)

Toate modificările API sunt documentate în fișierul CHANGELOG.md din depozit (repository).

Dată	Versiune	Tip	Descriere
Martie 2026	v1.0.0	Inițial	Prima versiune stabilă: coduri QR, redirecționare, Auth, Billing
Martie 2026	v1.1.0	Funcționalitate	Batch-API, destinații A/B, Expiry, export PDF
Martie 2026	v1.2.0	Funcționalitate	Organizations, Workspaces, Audit-Logs, Comments, endpoint-uri GDPR

---

Întrebări?

Pentru întrebări legate de politica de versiuni: [email protected]