Versionamento API & Policy LTS

Schema di versionamento

qr3.app utilizza il versionamento basato su URL: /v1/, /v2/, ecc.

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

L’attuale versione stabile è v1 LTS .

Ciclo di vita delle versioni

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

Versione	Stato	Supporto fino a	Note
v1	✅ Stabile (LTS)	Min. marzo 2027	Versione di produzione attuale
v2	📋 Pianificata	—	Roadmap: Fase 5+

Breaking Change — Definizione

Un breaking change è qualsiasi modifica che interrompe il funzionamento dei client esistenti senza un adeguamento:

Rimozione o ridenominazione di campi di richiesta/risposta
Modifica dei codici di stato HTTP per scenari esistenti
Rimozione di endpoint
Modifica del metodo di autenticazione
Modifiche incompatibili al formato degli errori

Non sono breaking change (estensioni compatibili):

Aggiunta di campi di richiesta opzionali
Aggiunta di nuovi campi di risposta
Nuovi endpoint
Nuovi parametri di query opzionali
Nuovi codici di errore (RFC 7807 rimane compatibile)

Comunicazione dei breaking change

I breaking change non vengono mai eseguiti senza preavviso:

Preavviso: Almeno 90 giorni prima del breaking change
Canale: Email a tutti gli utenti delle API + banner nella dashboard + CHANGELOG.md
Supporto alla migrazione: Guia alla migrazione ed esempi di codice
Header di deprecazione: L’API fornisce gli header 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"

Garanzie LTS (v1)

Per l’attuale versione LTS v1 si applica quanto segue:

Garanzia	Periodo
Nessun breaking change	Min. 12 mesi dallo stato stabile
Patch di sicurezza	Per l’intera durata del supporto LTS
Risoluzione dei bug	Per l’intera durata del supporto LTS
Modalità manutenzione	6 mesi dopo la fine del supporto LTS
Supporto completo	Almeno fino a marzo 2027

Identificare la versione

Ogni risposta dell’API contiene metadati sulla versione corrente:

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

L’endpoint GET /v1/health fornisce inoltre:

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

Migrazione tra versioni

Quando viene rilasciata una nuova versione principale, la vecchia versione rimane attiva in parallelo per almeno 6 mesi.

Forniamo:

Diff completo di tutti gli endpoint modificati
Strumento di migrazione automatica (ove possibile)
Supporto alla migrazione personalizzato per i clienti Business/Agency

Policy di deprecazione per singoli endpoint

I singoli endpoint possono essere contrassegnati come deprecati anche all’interno di una stessa versione:

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

Tutte le modifiche alle API sono documentate nel file CHANGELOG.md all’interno del repository.

Data	Versione	Tipo	Descrizione
Marzo 2026	v1.0.0	Iniziale	Primo rilascio stabile: codici QR, reindirizzamenti, autenticazione, fatturazione
Marzo 2026	v1.1.0	Feature	API batch, destinazioni A/B, scadenza, esportazione PDF
Marzo 2026	v1.2.0	Feature	Organizzazioni, workspace, log di audit, commenti, endpoint GDPR

Domande?

In caso di domande sulla policy di versionamento: [email protected]