API versioonihaldus ja LTS-poliitika

Versiooniskeem

qr3.app kasutab URL-ipõhist versioonihaldust: /v1/, /v2/ jne.

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

Praegune stabiilne versioon on v1 LTS .

Versiooni elutsükkel

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

Versioon	Staatus	Tugi kuni	Märkused
v1	✅ Stabiilne (LTS)	Vähemalt märts 2027	Praegune toodanguversioon
v2	📋 Planeeritud	—	Teekaart: Faas 5+

Breaking Changes — definitsioon

Breaking change (rikkuv muudatus) on mis tahes muudatus, mis lõhub olemasolevad kliendid ilma kohandamiseta:

Päringu (Request) või vastuse (Response) väljade eemaldamine oder ümbernimetamine
HTTP olekukoodide muutmine olemasolevate stsenaariumide puhul
Endpointide eemaldamine
Autentimismeetodi muutmine
Ühildumatud muudatused veavormingus

Mitte-rikkuvad muudatused (ühilduvad laiendused):

Valikuliste päringuväljade lisamine
Uute vastuseväljade lisamine
Uued endpointid
Uued valikulised päringuparameetrid (Query parameters)
Uued veakoodid (RFC 7807 jääb ühilduvaks)

Breaking Changes teavitamine

Breaking change’e ei tehta kunagi ilma etteteatamiseta:

Teavitus: Vähemalt 90 päeva enne breaking change’i
Kanal: E-kiri kõigile API kasutajatele + töölaua (Dashboard) bänner + CHANGELOG.md
Migratsiooniabi: Migratsioonijuhend ja koodinäited
Aegumise päised (Deprecation Headers): API tagastab Deprecation ja Sunset HTTP-päised

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

Praegusele LTS-versioonile v1 kehtib:

Garantii	Periood
Puuduvad breaking change’id	Vähemalt 12 kuud alates stabiilsest staatusest
Turvapaigad	Kogu LTS-i eluea jooksul
Veaparandused	Kogu LTS-i eluea jooksul
Hooldusrežiim	6 kuud pärast LTS-i lõppu
Täielik tugi	Vähemalt kuni märtsini 2027

Versiooni tuvastamine

Iga API vastus sisaldab metaandmeid praeguse versiooni kohta:

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

Endpoint GET /v1/health tagastab lisaks:

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

Versioonidevaheline migratsioon

Kui ilmub uus peaversioon, jääb vana versioon paralleelselt aktiivseks vähemalt 6 kuuks.

Me pakume:

Täielik erinevuste võrdlus (diff) kõigi muudetud endpointide kohta
Automaatne migratsioonitööriist (kus võimalik)
Personaalne migratsioonitugi äri- ja agentuuriklientidele (Business/Agency)

Üksikute endpointide aegumise poliitika (Deprecation Policy)

Üksikuid endpointe saab märkida aegunuks (deprecated) ka ühe versiooni siseselt:

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"

Muudatuste logi (Changelog)

Kõik API muudatused dokumenteeritakse hoidlas (repository) failis CHANGELOG.md.

Kuupäev	Versioon	Tüüp	Kirjeldus
Märts 2026	v1.0.0	Algne	Esimene stabiilne väljalase: QR-koodid, ümbersuunamine (Redirect), autentimine (Auth), arveldus (Billing)
Märts 2026	v1.1.0	Funktsioon	Batch-API, A/B sihtkohad (Destinations), aegumine (Expiry), PDF-eksport
Märts 2026	v1.2.0	Funktsioon	Organisatsioonid (Organizations), tööruumid (Workspaces), auditilogid (Audit-Logs), kommentaarid (Comments), GDPR-i endpointid

Küsimused?

Küsimuste korral versioonipoliitika kohta: [email protected]