API-versiebeheer & LTS-beleid

API-versiebeheer & LTS-beleid

Versiebeheerschema

qr3.app maakt gebruik van op URL gebaseerd versiebeheer: /v1/, /v2/, enz.

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

De huidige stabiele versie is v1 LTS .

---

Versielevenscyclus

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

Versie	Status	Support tot	Opmerkingen
v1	✅ Stable (LTS)	Min. maart 2027	Huidige productieversie
v2	📋 Gepland	—	Roadmap: Fase 5+

---

Breaking Changes — Definitie

Een breaking change is elke wijziging die bestaande clients zonder aanpassing defect maakt:

• Verwijderen of hernoemen van request-/responsevelden
• Wijzigen van HTTP-statuscodes voor bestaande scenario’s
• Verwijderen van endpoints
• Wijzigen van de authenticatiemethode
• Incompatibele wijzigingen aan het foutformaat

Geen breaking changes (compatibele uitbreidingen):

• Toevoegen van optionele requestvelden
• Toevoegen van nieuwe responsevelden
• Nieuwe endpoints
• Nieuwe optionele queryparameters
• Nieuwe foutcodes (RFC 7807 blijft compatibel)

---

Communicatie van breaking changes

Breaking changes worden nooit zonder aankondiging doorgevoerd:

1. Aankondiging: Minimaal 90 dagen voor de breaking change
2. Kanaal: E-mail naar alle API-gebruikers + dashboardbanner + CHANGELOG.md
3. Migratiehulp: Migratiegids en codevoorbeelden
4. Deprecation-headers: API levert Deprecation + Sunset HTTP-headers

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

Voor de huidige LTS-versie v1 geldt:

Garantie	Periode
Geen breaking changes	Min. 12 maanden vanaf stable-status
Security patches	Voor de gehele LTS-looptijd
Bugfixes	Voor de gehele LTS-looptijd
Maintenance-modus	6 maanden na LTS-einde
Volledige ondersteuning	Min. tot maart 2027

Versiebeheer in de SDK

De TypeScript SDK (@qr3/sdk) en de CLI (@qr3/cli) volgen eveneens SemVer. Breaking changes in de SDK weerspiegelen altijd breaking changes in de API.

---

Versie herkennen

Elke API-respons bevat metadata over de huidige versie:

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

Het GET /v1/health endpoint levert daarnaast:

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

---

Migratie tussen versies

Wanneer er een nieuwe hoofdversie verschijnt, blijft de oude versie minimaal 6 maanden parallel actief.

Wij bieden:

• Volledige diff van alle gewijzigde endpoints
• Automatische migratietool (waar mogelijk)
• Persoonlijke migratie-ondersteuning voor Business/Agency-klanten

---

Deprecation-beleid voor afzonderlijke endpoints

Afzonderlijke endpoints kunnen ook binnen een versie als deprecated worden gemarkeerd:

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"

Opgepast

Negeer Deprecation-headers niet. Endpoints worden na de Sunset-datum verwijderd, zelfs als ze nog geen breaking change waren.

---

Changelog

Alle API-wijzigingen worden gedocumenteerd in CHANGELOG.md in de repository.

Datum	Versie	Type	Beschrijving
Maart 2026	v1.0.0	Initieel	Eerste stabiele release: QR-codes, Redirect, Auth, Billing
Maart 2026	v1.1.0	Feature	Batch-API, A/B-bestemmingen, Expiry, PDF-export
Maart 2026	v1.2.0	Feature	Organizations, Workspaces, Audit-logs, Comments, GDPR-endpoints

---

Vragen?

Bij vragen over het versiebeheerbeleid: [email protected]