Skip to content
qr3.app Docs

Версиониране на API & LTS политика

Версиониране на API & LTS политика

Схема на версиониране

qr3.app използва версиониране, базирано на URL: /v1/, /v2/ и т.н.

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)
ВерсияСтатусПоддръжка доБележки
v1✅ Stable (LTS)Мин. март 2027 г.Текуща производствена версия
v2📋 Планирана—Пътна карта: Фаза 5+

Дефиниция за Breaking Changes

Breaking Change е всяка промяна, която нарушава работата на съществуващите клиенти без допълнителна адаптация:

  • Премахване или преименуване на полета в заявката (Request) или отговора (Response)
  • Промяна на HTTP статус кодове за съществуващи сценарии
  • Премахване на крайни точки (Endpoints)
  • Промяна на метода за автентификация
  • Несъвместими промени във формата на грешките

Не са Breaking Changes (съвместими разширения):

  • Добавяне на незадължителни полета в заявката
  • Добавяне на нови полета в отговора
  • Нови крайни точки (Endpoints)
  • Нови незадължителни параметри на заявката (Query parameters)
  • Нови кодове за грешки (RFC 7807 остава съвместим)

Комуникация при Breaking Changes

Breaking Changes никога не се извършват без предизвестие:

  1. Предизвестие: Най-малко 90 дни преди извършването на Breaking Change
  2. Канал: Имейл до всички потребители на API + банер в таблото за управление (Dashboard) + CHANGELOG.md
  3. Помощ при миграция: Ръководство за миграция и примери за код
  4. Заглавки за оттегляне (Deprecation Headers): API предоставя 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"

LTS гаранции (v1)

За текущата LTS версия v1 важи следното:

ГаранцияПериод
Без Breaking ChangesМин. 12 месеца от получаване на статус Stable
Пачове за сигурност (Security Patches)За целия период на LTS
Корекции на грешки (Bug Fixes)За целия период на LTS
Режим на поддръжка (Maintenance Mode)6 месеца след края на LTS
Пълна поддръжкаМин. до март 2027 г.

Разпознаване на версията

Всеки отговор (Response) от API съдържа метаданни за текущата версия:

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

Крайната точка GET /v1/health допълнително връща:

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

Миграция между версиите

Когато се появи нова основна версия, старата версия остава активна паралелно в продължение на поне 6 месеца.

Ние предоставяме:

  • Пълен списък с разликите (Diff) за всички променени крайни точки
  • Инструмент за автоматична миграция (където е възможно)
  • Персонална поддръжка при миграция за клиенти с планове Business/Agency

Политика за оттегляне на отделни крайни точки

Отделни крайни точки могат да бъдат маркирани като остарели (deprecated) дори в рамките на една и съща версия:

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)

Всички промени в API се документират във файла CHANGELOG.md в хранилището.

ДатаВерсияТипОписание
Март 2026 г.v1.0.0ПървоначалнаПърва стабилна версия: QR кодове, Redirect, Auth, Billing
Март 2026 г.v1.1.0ФункцияBatch-API, A/B-Destinations, Expiry, PDF-Export
Март 2026 г.v1.2.0ФункцияOrganizations, Workspaces, Audit-Logs, Comments, DSGVO-Endpoints

Въпроси?

При въпроси относно политиката за версиониране: [email protected]