C# Academy · Lezione

Strategie di versionamento delle API

Gestisca le versioni tramite URL, header e stringa di query.

Strategie di versionamento delle API è una lezione C# Academy gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento C# Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso C# Academy include 4 lezioni in totale.

Perché creare versioni di un'API?

Una volta che i client dipendono dalla Sua API, non può interromperne il contratto. Il versioning consente di distribuire modifiche incompatibili in una nuova versione, mentre i client esistenti continuano a funzionare con quella precedente.

// v1 returns { name }
// v2 returns { firstName, lastName }  (breaking)

Versioning nel percorso URL

La strategia più visibile inserisce la versione nel percorso. È non ambigua e semplifica il routing, la consultazione e il caching.

GET /api/v1/products
GET /api/v2/products

Versioning nella stringa di query

La versione viene trasmessa come parametro di query. Gli URL rimangono stabili e, se il parametro manca, è possibile utilizzare come valore predefinito la versione più recente o una versione fissa.

GET /api/products?api-version=1.0
GET /api/products?api-version=2.0

Versioning tramite header

Un header della richiesta personalizzato contiene la versione, mantenendo pulito l'URL. Lo svantaggio è che la versione non è visibile nella barra degli indirizzi del browser ed è più difficile da testare manualmente.

GET /api/products
X-Api-Version: 2.0

Versioning tramite media type

Chiamato anche content negotiation. La versione è incorporata nel media type dell'header Accept. È l'opzione più RESTful, ma anche la meno intuitiva da individuare.

GET /api/products
Accept: application/json;v=2.0

Confrontare le strategie

Ogni strategia rappresenta un compromesso tra facilità di individuazione e pulizia dell'URL:

Percorso URL: massima facilità di individuazione, ma URL più ingombranti.
Stringa di query: URL stabili e valori predefiniti semplici.
Header: URL puliti, ma versione nascosta nei browser.
Media type: approccio REST più puro, ma più difficile da utilizzare.

// Many teams pick URL path for public APIs

Semantic versioning delle API

Le versioni delle API sono generalmente indicate solo con la versione major (v1, v2). Riservi le versioni minor alle modifiche aggiuntive e non incompatibili che i client precedenti possono ignorare.

// v1.0 -> v1.1 : additive (safe)
// v1   -> v2   : breaking (new version)

Deprecazione

Non rimuova mai bruscamente una versione precedente. La contrassegni come deprecata, comunichi una data di dismissione e la segnali ai client tramite gli header.

// Response header on a deprecated version:
// Sunset: Wed, 31 Dec 2026 23:59:59 GMT
// Deprecation: true

Versione predefinita

Decida cosa accade quando un client non invia alcuna versione. Scelte comuni: assumere la versione più recente, assumere la v1 oppure rifiutare la richiesta. Essere espliciti evita sorprese.

// Strategy: unversioned request -> treat as v1.0

Creare versioni degli elementi giusti

Crei versioni del contratto (route e strutture delle richieste e delle risposte), non dei dettagli dell'implementazione interna. Un endpoint v2 può condividere la maggior parte della logica di business con il v1.

// Same service, two thin controllers:
// ProductsV1Controller, ProductsV2Controller

Combinare le strategie

La libreria di versioning di ASP.NET Core può leggere la versione da più origini contemporaneamente, consentendo ai client di scegliere quella più comoda. La configurerà nella prossima sezione.

// Accept version from URL OR header OR query

Verifica rapida

Verifichi la Sua comprensione delle strategie di versioning.

Riepilogo

Ha esaminato le strategie di versioning delle API:

percorso URL, stringa di query, header e media type.
Ognuna rappresenta un compromesso tra facilità di individuazione e pulizia dell'URL.
Crei versioni del contratto, gestisca la deprecazione in modo graduale e definisca un valore predefinito.

Successivo: configurare Asp.Versioning in ASP.NET Core.

Domande Frequenti

La lezione «Strategie di versionamento delle API» è gratuita?

Sì — il testo completo di «Strategie di versionamento delle API» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso C# Academy, passa a CoddyKit PRO. Il corso C# Academy include 4 lezioni in totale.

Cosa imparerò in «Strategie di versionamento delle API»?

Gestisca le versioni tramite URL, header e stringa di query. Eserciti C# Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.

Ho bisogno di esperienza per iniziare C# Academy?

Non è richiesta alcuna esperienza precedente. C# Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.

Quanto tempo richiede la lezione «Strategie di versionamento delle API»?

La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.

Posso scrivere ed eseguire codice in questa lezione C# Academy?

Sì. Ogni lezione C# Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.

Tutte le lezioni di questo corso

← Torna a C# Academy