Wersjonowanie API i polityka LTS

Schemat wersjonowania

qr3.app używa wersjonowania opartego na adresach URL: /v1/, /v2/ itd.

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

Aktualna stabilna wersja to v1 LTS .

Cykl życia wersji

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

Wersja	Status	Wsparcie do	Uwagi
v1	✅ Stable (LTS)	Min. marzec 2027	Aktualna wersja produkcyjna
v2	📋 Planowana	—	Roadmap: Faza 5+

Zmiany niekompatybilne (Breaking Changes) — Definicja

Breaking Change (zmiana niekompatybilna wstecz) to każda zmiana, która powoduje błędy w działaniu istniejących klientów bez ich dostosowania:

Usuwanie lub zmiana nazw pól żądania (Request) / odpowiedzi (Response)
Zmiana kodów statusu HTTP dla istniejących scenariuszy
Usuwanie punktów końcowych (Endpoints)
Zmiana metody uwierzytelniania
Niekompatybilne zmiany w formacie błędów

Nie są zmianami niekompatybilnymi (rozszerzenia kompatybilne wstecz):

Dodawanie opcjonalnych pól żądania
Dodawanie nowych pól odpowiedzi
Nowe punkty końcowe (Endpoints)
Nowe opcjonalne parametry zapytania (Query)
Nowe kody błędów (RFC 7807 pozostaje kompatybilny)

Komunikowanie zmian niekompatybilnych

Zmiany niekompatybilne nigdy nie są wprowadzane bez zapowiedzi:

Zapowiedź: Co najmniej 90 dni przed wprowadzeniem zmiany
Kanał: E-mail do wszystkich użytkowników API + baner w panelu (Dashboard) + CHANGELOG.md
Pomoc w migracji: Przewodnik migracji i przykłady kodu
Nagłówki Deprecation: API zwraca nagłówki 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"

Gwarancje LTS (v1)

Dla aktualnej wersji LTS v1 obowiązują następujące zasady:

Gwarancja	Okres
Brak zmian niekompatybilnych	Min. 12 miesięcy od uzyskania statusu Stable
Łatki bezpieczeństwa (Security Patches)	Przez cały okres wsparcia LTS
Poprawki błędów (Bug Fixes)	Przez cały okres wsparcia LTS
Tryb konserwacji (Maintenance Mode)	6 miesięcy po zakończeniu LTS
Pełne wsparcie	Co najmniej do marca 2027

Identyfikacja wersji

Każda odpowiedź API zawiera metadane dotyczące aktualnej wersji:

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

Punkt końcowy GET /v1/health dodatkowo zwraca:

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

Migracja między wersjami

Po wydaniu nowej wersji głównej, stara wersja pozostaje aktywna równolegle przez co najmniej 6 miesięcy.

Zapewniamy:

Pełne zestawienie różnic (diff) dla wszystkich zmienionych punktów końcowych
Automatyczne narzędzie migracyjne (tam, gdzie to możliwe)
Osobiste wsparcie migracyjne dla klientów planów Business/Agency

Polityka wycofywania (Deprecation) dla poszczególnych punktów końcowych

Poszczególne punkty końcowe mogą zostać oznaczone jako przestarzałe (deprecated) również w ramach jednej wersji:

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"

Dziennik zmian (Changelog)

Wszystkie zmiany w API są dokumentowane w pliku CHANGELOG.md w repozytorium.

Data	Wersja	Typ	Opis
Marzec 2026	v1.0.0	Initial	Pierwsze stabilne wydanie: kody QR, przekierowania (Redirect), Auth, Billing
Marzec 2026	v1.1.0	Feature	Batch-API, cele A/B (A/B-Destinations), wygasanie (Expiry), eksport do PDF
Marzec 2026	v1.2.0	Feature	Organizacje (Organizations), obszary robocze (Workspaces), dzienniki audytu (Audit-Logs), komentarze (Comments), punkty końcowe RODO (DSGVO-Endpoints)

Pytania?

W przypadku pytań dotyczących polityki wersjonowania: [email protected]