Versioning

La versione sta nel percorso: /api/v2. Non impostare l’header X-API-Version: accetta solo v1 e farebbe fallire la chiamata con 400.

v1 vs v2

	v1	v2
Percorso	rotte interne dell’app (/api/…)	/api/v2/…, superficie isolata e versionata
Forma risposta	forme del database, non standardizzate	busta stabile { data, meta } / { error }
Stato	deprecata per le chiavi API	attiva, superficie consigliata
Compatibilità	resta accessibile per compatibilità	additiva: si aggiungono risorse/campi, non se ne rimuovono

La v1 — le rotte usate dall’app — resta accessibile alle chiavi API per compatibilità, ma è deprecata: le risposte portano Deprecation: true e la data di spegnimento (Sunset: 2027-03-08). Ogni versione nuova ha almeno 12 mesi di sovrapposizione con la precedente: nessuna rotta pubblica sparisce da un giorno all’altro.

Compatibilità del contratto v2

Il contratto v2 è stabile: nessun cambiamento incompatibile al suo interno.

• Permesso: aggiungere nuove risorse, nuovi campi ai DTO esistenti.
• Non permesso: rimuovere o rinominare un campo pubblico, cambiare il significato di un error.code — questo genere di cambiamento richiede una v3, non un aggiornamento di v2.

Se stai integrando oggi, puoi farlo con la certezza che una chiamata che funziona continuerà a funzionare: i campi possono solo aggiungersi, non sparire o cambiare forma.