API-Versionierung & LTS-Policy

API-Versionierung & LTS-Policy

Versionierungsschema

qr3.app verwendet URL-basierte Versionierung: /v1/, /v2/, usw.

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

Die aktuelle stabile Version ist v1 LTS .

---

Versionslebenszyklus

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

Version	Status	Support bis	Notizen
v1	✅ Stable (LTS)	Min. März 2027	Aktuelle Produktionsversion
v2	📋 Geplant	—	Roadmap: Phase 5+

---

Breaking Changes — Definition

Ein Breaking Change ist jede Änderung, die bestehende Clients ohne Anpassung kaputt macht:

• Entfernen oder Umbenennen von Request-/Response-Feldern
• Änderung von HTTP-Statuscodes für bestehende Szenarien
• Entfernen von Endpoints
• Änderung der Authentifizierungsmethode
• Inkompatible Änderungen am Fehlerformat

Keine Breaking Changes (kompatible Erweiterungen):

• Hinzufügen optionaler Request-Felder
• Hinzufügen neuer Response-Felder
• Neue Endpoints
• Neue optionale Query-Parameter
• Neue Fehlercodes (RFC 7807 bleibt kompatibel)

---

Kommunikation von Breaking Changes

Breaking Changes werden nie ohne Ankündigung durchgeführt:

1. Ankündigung: Mindestens 90 Tage vor dem Breaking Change
2. Kanal: E-Mail an alle API-Nutzer + Dashboard-Banner + CHANGELOG.md
3. Migrationshilfe: Migrationsleitfaden und Codebeispiele
4. Deprecation-Header: API liefert Deprecation + Sunset HTTP-Header

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

Für die aktuelle LTS-Version v1 gilt:

Garantie	Zeitraum
Keine Breaking Changes	Min. 12 Monate ab Stable-Status
Security Patches	Für die gesamte LTS-Laufzeit
Bug Fixes	Für die gesamte LTS-Laufzeit
Maintenance Mode	6 Monate nach LTS-Ende
Vollständiger Support	Min. bis März 2027

Versionierung im SDK

Das TypeScript SDK (@qr3/sdk) und die CLI (@qr3/cli) folgen ebenfalls SemVer. Breaking Changes im SDK spiegeln stets Breaking Changes in der API wider.

---

Version erkennen

Jede API-Response enthält Metadaten zur aktuellen Version:

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

Der GET /v1/health Endpoint liefert zusätzlich:

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

---

Migration zwischen Versionen

Wenn eine neue Hauptversion erscheint, bleibt die alte Version mindestens 6 Monate parallel aktiv.

Wir stellen bereit:

• Vollständiger Diff aller geänderten Endpoints
• Automatisches Migrationstool (wo möglich)
• Persönlicher Migrations-Support für Business/Agency-Kunden

---

Deprecation-Policy für einzelne Endpoints

Einzelne Endpoints können auch innerhalb einer Version als deprecated markiert werden:

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"

Achtung

Ignoriere Deprecation-Header nicht. Endpoints werden nach dem Sunset-Datum entfernt, auch wenn sie noch keine Breaking Change waren.

---

Changelog

Alle API-Änderungen werden in CHANGELOG.md im Repository dokumentiert.

Datum	Version	Art	Beschreibung
März 2026	v1.0.0	Initial	Erstes stabiles Release: QR-Codes, Redirect, Auth, Billing
März 2026	v1.1.0	Feature	Batch-API, A/B-Destinations, Expiry, PDF-Export
März 2026	v1.2.0	Feature	Organizations, Workspaces, Audit-Logs, Comments, DSGVO-Endpoints

---

Fragen?

Bei Fragen zur Versionierungspolitik: [email protected]