Verżjonar tal-API & Politika LTS

Skema ta’ Verżjonar

qr3.app juża verżjonar ibbażat fuq il-URL: /v1/, /v2/, eċċ.

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

Il-verżjoni stabbli attwali hija v1 LTS .

Ċiklu tal-Ħajja tal-Verżjoni

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

Verżjoni	Status	Appoġġ sa	Noti
v1	✅ Stable (LTS)	Min. Marzu 2027	Verżjoni attwali tal-produzzjoni
v2	📋 Ippjanata	—	Roadmap: Fażi 5+

Breaking Changes — Definizzjoni

Breaking Change hija kwalunkwe bidla li tħarbat il-klijenti eżistenti mingħajr aġġustament:

Tneħħija u tibdil fl-isem ta’ oqsma ta’ Request/Response
Bidla fil-kodiċijiet tal-istatus HTTP għal xenarji eżistenti
Tneħħija ta’ Endpoints
Bidla fil-metodu ta’ awtentikazzjoni
Bidliet inkompatibbli fil-format tal-iżbalji

Mhumiex Breaking Changes (estensjonijiet kompatibbli):

Żieda ta’ oqsma ta’ Request mhux obbligatorji
Żieda ta’ oqsma ġodda ta’ Response
Endpoints ġodda
Query parameters ġodda mhux obbligatorji
Kodiċijiet ta’ żbalji ġodda (RFC 7807 jibqa’ kompatibbli)

Komunikazzjoni ta’ Breaking Changes

Breaking Changes qatt ma jsiru mingħajr avviż:

Avviż: Mill-inqas 90 jum qabel il-Breaking Change
Kanal: Email lill-utenti kollha tal-API + banner fuq id-Dashboard + CHANGELOG.md
Għajnuna għall-Migrazzjoni: Gwida għall-migrazzjoni u eżempji ta’ kodiċi
Deprecation Headers: L-API tipprovdi l-headers 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"

Garanziji LTS (v1)

Għall-verżjoni LTS attwali v1 japplika dan li ġej:

Garanzija	Perjodu
L-ebda Breaking Change	Min. 12-il xahar mill-istatus Stable
Security Patches	Għat-tul kollu tal-LTS
Bug Fixes	Għat-tul kollu tal-LTS
Maintenance Mode	6 xhur wara t-tmiem tal-LTS
Appoġġ sħiħ	Min. sa Marzu 2027

Kif Tagħraf il-Verżjoni

Kull rispons tal-API fih metadata dwar il-verżjoni attwali:

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

L-endpoint GET /v1/health jipprovdi wkoll:

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

Migrazzjoni bejn il-Verżjonijiet

Meta toħroġ verżjoni ewlenija ġdida, il-verżjoni l-antika tibqa’ attiva b’mod parallel għal mill-inqas 6 xhur.

Aħna nipprovdu:

Diff sħiħ tal-endpoints kollha mibdula
Għodda ta’ migrazzjoni awtomatika (fejn possibbli)
Appoġġ personali għall-migrazzjoni għal klijenti Business/Agency

Politika ta’ Deprecation għal Endpoints Individwali

Endpoints individwali jistgħu wkoll jiġu mmarkati bħala deprecated fi ħdan verżjoni partikolari:

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

Il-bidliet kollha fl-API huma ddokumentati f’CHANGELOG.md fir-repożitorju.

Data	Verżjoni	Tip	Deskrizzjoni
Marzu 2026	v1.0.0	Inizjali	L-ewwel rilaxx stabbli: QR-Codes, Redirect, Auth, Billing
Marzu 2026	v1.1.0	Feature	Batch-API, A/B-Destinations, Expiry, PDF-Export
Marzu 2026	v1.2.0	Feature	Organizations, Workspaces, Audit-Logs, Comments, endpoints tal-GDPR

Mistoqsijiet?

Għal mistoqsijiet dwar il-politika tal-verżjonar: [email protected]