API-versiointi & LTS-käytäntö

API-versiointi & LTS-käytäntö

Versiointikaavio

qr3.app käyttää URL-pohjaista versiointia: /v1/, /v2/ jne.

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

Nykyinen vakaa versio on v1 LTS .

---

Version elinkaari

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

Versio	Tila	Tuki asti	Huomautukset
v1	✅ Stable (LTS)	Väh. maaliskuu 2027	Nykyinen tuotantoversio
v2	📋 Suunniteltu	—	Roadmap: Vaihe 5+

---

Rikkovat muutokset (Breaking Changes) — Määritelmä

Rikkova muutos (Breaking Change) on mikä tahansa muutos, joka rikkoo olemassa olevat asiakasohjelmat ilman mukautuksia:

• Pyyntö- (Request) tai vastauskenttien (Response) poistaminen tai nimeäminen uudelleen
• HTTP-tilakoodien muuttaminen olemassa olevissa skenaarioissa
• Päätepisteiden (Endpoints) poistaminen
• Tunnistautumismenetelmän muuttaminen
• Yhteensopimattomat muutokset virhemuotoon

Ei rikkova muutos (yhteensopivat laajennukset):

• Valinnaisten pyyntökenttien lisääminen
• Uusien vastauskenttien lisääminen
• Uudet päätepisteet
• Uudet valinnaiset kyselyparametrit (Query-Parameter)
• Uudet virhekoodit (RFC 7807 säilyy yhteensopivana)

---

Rikkovista muutoksista viestiminen

Rikkovia muutoksia ei koskaan tehdä ilman ilmoitusta:

1. Ilmoitus: Vähintään 90 päivää ennen rikkovaa muutosta
2. Kanava: Sähköposti kaikille API-käyttäjille + hallintapaneelin banneri + CHANGELOG.md
3. Migraatioapu: Migraatio-opas ja koodiesimerkit
4. Deprecation-otsikot: API palauttaa Deprecation- ja Sunset-HTTP-otsikot

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

Seuraavat takuut koskevat nykyistä LTS-versiota v1:

Takuu	Aikaväli
Ei rikkovia muutoksia	Väh. 12 kuukautta Stable-tilasta alkaen
Tietoturvakorjaukset (Security Patches)	Koko LTS-elinkaaren ajan
Virhekorjaukset (Bug Fixes)	Koko LTS-elinkaaren ajan
Ylläpitotila (Maintenance Mode)	6 kuukautta LTS-kauden päättymisen jälkeen
Täysi tuki	Vähintään maaliskuuhun 2027 asti

Versionierung im SDK

Myös TypeScript SDK (@qr3/sdk) ja CLI (@qr3/cli) noudattavat SemVer-versiointia. SDK:n rikkova muutos heijastaa aina vastaavaa rikkovaa muutosta API:ssa.

---

Version tunnistaminen

Jokainen API-vastaus sisältää metatiedot nykyisestä versiosta:

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

Päätepiste GET /v1/health palauttaa lisäksi:

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

---

Versioiden välinen migraatio

Kun uusi pääversio julkaistaan, vanha versio pysyy rinnakkain aktiivisena vähintään 6 kuukautta.

Tarjoamme:

• Täydellisen vertailun (Diff) kaikista muuttuneista päätepisteistä
• Automaattisen migraatiotyökalun (mahdollisuuksien mukaan)
• Henkilökohtaisen migraatiotuen Business- ja Agency-asiakkaille

---

Yksittäisten päätepisteiden Deprecation-käytäntö

Yksittäisiä päätepisteitä voidaan merkitä vanhentuneiksi (deprecated) myös saman version sisällä:

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"

Caution

Älä jätä Deprecation-otsikoita huomiotta. Päätepisteet poistetaan Sunset-päivämäärän jälkeen, vaikka ne eivät vielä olisi olleet rikkova muutos.

---

Muutosloki (Changelog)

Kaikki API-muutokset dokumentoidaan arkiston CHANGELOG.md-tiedostoon.

Päivämäärä	Versio	Tyyppi	Kuvaus
Maaliskuu 2026	v1.0.0	Alkuperäinen	Ensimmäinen vakaa julkaisu: QR-koodit, uudelleenohjaus, Auth, laskutus
Maaliskuu 2026	v1.1.0	Ominaisuus	Erä-API (Batch-API), A/B-kohteet, vanhentuminen, PDF-vienti
Maaliskuu 2026	v1.2.0	Ominaisuus	Organisaatiot, työtilat, lokitiedot (Audit-Logs), kommentit, GDPR-päätepisteet

---

Kysyttävää?

Jos sinulla on kysyttävää versiointikäytännöstä: [email protected]