Versioning
Este conteúdo não está disponível em sua língua ainda.
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
Sezione intitolata “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
Sezione intitolata “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.