Versioning

La versione sta nel percorso: /api/v2, /api/v3. Sulle rotte con la versione nel percorso l’header X-API-Version non serve e viene ignorato, non blocca la chiamata: la decide sempre il percorso. Fa eccezione la v1 (le rotte interne dell’app, raggiungibili da una chiave per compatibilità): lì non c’è un percorso versionato, quindi la versione la decide l’header X-API-Version, che accetta solo il valore v1 (il default, se lo ometti) — un valore diverso resta rifiutato con 400.

v1 vs v2 vs v3

	v1	v2	v3 (beta)
Percorso	rotte interne dell’app (/api/…)	/api/v2/…	/api/v3/…
Risorse	tutte quelle raggiungibili da una chiave (dispositivi, storico, comandi…)	dispositivi, posizioni, storico, eventi (sola lettura)	le stesse della v2 (stesso codice, sotto /api/v3) più aree/geofence (lettura e scrittura) — la v2 resta invariata accanto, si può usare solo la v3
Forma risposta	forme del database, non standardizzate	busta stabile { data, meta } / { error }	stessa busta della v2, con details[] sugli errori di validazione
Header versione	X-API-Version (solo v1)	dal percorso, ignorato se inviato	dal percorso, ignorato se inviato; ogni risposta porta anche X-API-Status: beta
Stato	deprecata per le chiavi API	attiva, superficie consigliata	beta: può ancora cambiare, sempre con preavviso
Compatibilità	resta accessibile per compatibilità	additiva: si aggiungono risorse/campi, non se ne rimuovono	additiva, ma non ancora congelata — vedi Panoramica API v3

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.

Le risposte di /api/v2 e /api/v3, invece, non portano Deprecation né Sunset: sono entrambe superfici attive (una stabile, una beta), non in via di spegnimento.

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.

La v3 è beta

La v3 non sostituisce la v2, la affianca: include tutta la v2 (dispositivi, posizioni, storico, comandi, eventi, stesso codice) sotto /api/v3, più le aree (geofence), che nessuna versione precedente esponeva — si può integrare solo con la v3. Finché è beta i suoi dettagli possono ancora affinarsi (sempre annunciato prima di cambiare) — vedi API v3: panoramica e Da v2 a v3 per il confronto completo con la v2.