Come usare il controllo delle versioni delle API in ASP.NET Core

Quando sviluppi le API, dovresti tenere a mente una cosa: il cambiamento è inevitabile. Quando la tua API ha raggiunto un punto in cui devi aggiungere più responsabilità, dovresti prendere in considerazione il controllo delle versioni della tua API. Quindi avrai bisogno di una strategia di controllo delle versioni.

Esistono diversi approcci al controllo delle versioni delle API e ognuno di essi ha i suoi pro e contro. Questo articolo discuterà le sfide del controllo delle versioni delle API e come è possibile lavorare con il pacchetto di controllo delle versioni MVC ASP.NET Core di Microsoft per la versione delle API RESTful incorporate in ASP.NET Core. Puoi leggere di più sul controllo delle versioni dell'API Web nel mio precedente articolo qui. 

Creare un progetto API ASP.NET Core 3.1

Prima di tutto, creiamo un progetto ASP.NET Core in Visual Studio. Supponendo che Visual Studio 2019 sia installato nel sistema, seguire i passaggi descritti di seguito per creare un nuovo progetto ASP.NET Core in Visual Studio.

  1. Avvia l'IDE di Visual Studio.
  2. Fai clic su "Crea nuovo progetto".
  3. Nella finestra "Crea nuovo progetto", seleziona "Applicazione Web ASP.NET Core" dall'elenco dei modelli visualizzati.
  4. Fare clic su Avanti.
  5. Nella finestra "Configura il tuo nuovo progetto" mostrata di seguito, specifica il nome e la posizione per il nuovo progetto.
  6. Fare clic su Crea.
  7. Nella finestra "Crea nuova applicazione Web ASP.NET Core", seleziona .NET Core come runtime e ASP.NET Core 3.1 (o successivo) dall'elenco a discesa in alto. Userò ASP.NET Core 3.1 qui.
  8. Seleziona "API" come modello di progetto per creare una nuova applicazione API ASP.NET Core. 
  9. Assicurati che le caselle di controllo "Abilita supporto Docker" e "Configura per HTTPS" siano deselezionate poiché non utilizzeremo queste funzionalità qui.
  10. Assicurati che l'autenticazione sia impostata su "Nessuna autenticazione" poiché non utilizzeremo nemmeno l'autenticazione.
  11. Fare clic su Crea. 

Questo creerà un nuovo progetto API ASP.NET Core in Visual Studio. Selezionare la cartella della soluzione Controller nella finestra Esplora soluzioni e fare clic su "Aggiungi -> Controller ..." per creare un nuovo controller denominato DefaultController.

Sostituisci il codice sorgente della classe DefaultController con il codice seguente.

    [Route ("api / [controller]")]

    [ApiController]

    public class DefaultController: ControllerBase

    {

        stringa [] autori = nuova stringa []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        public IEnumerable Get ()

        {

            autori di ritorno;

        }

    }

Useremo questo controller nelle sezioni successive di questo articolo.

Per implementare il controllo delle versioni delle API in ASP.NET Core è necessario eseguire le operazioni seguenti:

  1. Installa il pacchetto di controllo delle versioni di ASP.NET Core MVC.
  2. Configurare il controllo delle versioni delle API nella classe Startup.
  3. Annota i controller e le azioni con gli attributi appropriati.

Installa il pacchetto di controllo delle versioni di ASP.NET Core MVC

ASP.NET Core fornisce il supporto per il controllo delle versioni delle API out-of-the-box. Per sfruttare il controllo delle versioni dell'API, tutto ciò che devi fare è installare il pacchetto Microsoft.AspNetCore.Mvc.Versioning da NuGet. Puoi farlo tramite il gestore di pacchetti NuGet all'interno dell'IDE di Visual Studio 2019 o eseguendo il comando seguente nella console del gestore di pacchetti NuGet:

Pacchetto di installazione Microsoft.AspNetCore.Mvc.Versioning

Tieni presente che se utilizzi l'API Web ASP.NET, devi aggiungere il pacchetto Microsoft.AspNet.WebApi.Versioning.

Configurare il controllo delle versioni delle API in ASP.NET Core

Ora che il pacchetto necessario per il controllo delle versioni dell'API è stato installato nel progetto, è possibile configurare il controllo delle versioni dell'API nel metodo ConfigureServices della classe Startup. Il frammento di codice seguente illustra come ottenere questo risultato.

public void ConfigureServices (servizi IServiceCollection)

{

  services.AddControllers ();

  services.AddApiVersioning ();

}

Quando effettui una richiesta Get alla tua API, ti verrà presentato l'errore mostrato nella Figura 1.

Per risolvere questo errore, è possibile specificare la versione predefinita quando si aggiungono i servizi di controllo delle versioni API al contenitore. Potresti anche voler utilizzare una versione predefinita se una versione non è specificata nella richiesta. Il frammento di codice seguente mostra come impostare una versione predefinita come 1.0 utilizzando la proprietà AssumeDefaultVersionWhenUnspecified se le informazioni sulla versione non sono disponibili nella richiesta.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = new ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

});

Notare come la versione principale e la versione secondaria vengono passate al costruttore della classe ApiVersion al momento dell'assegnazione della versione predefinita. La proprietà AssumeDefaultVersionWhenUnspecified può contenere valori true o false. Se è vero, verrà utilizzata la versione predefinita specificata durante la configurazione del controllo delle versioni API se non sono disponibili informazioni sulla versione.

Il codice sorgente completo del metodo ConfigureServices è fornito di seguito per riferimento.

public void ConfigureServices (servizi IServiceCollection)

{

    services.AddControllers ();

    services.AddApiVersioning (config =>

    {

         config.DefaultApiVersion = new ApiVersion (1, 0);

         config.AssumeDefaultVersionWhenUnspecified = true;

    });

}

Poiché non hai specificato alcuna informazione sulla versione, tutti gli endpoint avranno la versione predefinita 1.0.

Segnala tutte le versioni supportate della tua API

Potresti voler consentire ai client dell'API di conoscere tutte le versioni supportate. Per fare ciò, dovresti sfruttare la proprietà ReportApiVersions come mostrato nello snippet di codice riportato di seguito.

services.AddApiVersioning (config =>

{

  config.DefaultApiVersion = new ApiVersion (1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

});

Usa versioni nel controller e metodi di azione

Ora aggiungiamo alcune versioni supportate al nostro controller utilizzando gli attributi come mostrato nello snippet di codice riportato di seguito.

    [Route ("api / [controller]")]

    [ApiController]

    [ApiVersion ("1.0")]

    [ApiVersion ("1.1")]

    [ApiVersion ("2.0")]

    public class DefaultController: ControllerBase

    {

        stringa [] autori = nuova stringa []

        {"Joydip Kanjilal", "Steve Smith", "Anand John"};

        [HttpGet]

        public IEnumerable Get ()

        {

            autori di ritorno;

        }

    }

Quando effettui una richiesta Get da un client HTTP come Postman, ecco come verranno segnalate le versioni.

Puoi segnalare anche le versioni deprecate. A tale scopo, è necessario passare un parametro aggiuntivo al metodo ApiVersion come mostrato nello snippet di codice riportato di seguito.

[ApiVersion ("1.0", Deprecated = true)]

Eseguire il mapping a una versione specifica di un metodo di azione

C'è un altro attributo importante chiamato MapToApiVersion. Puoi usarlo per eseguire il mapping a una versione specifica di un metodo di azione. Il frammento di codice seguente mostra come eseguire questa operazione.

[HttpGet ("{id}")]

[MapToApiVersion ("2.0")]

stringa pubblica Get (int id)

{

   autori di ritorno [id];

}

Esempio completo di controllo delle versioni delle API in ASP.NET Core

Ecco il codice sorgente completo di DefaultController come riferimento.

[Route ("api / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

[ApiVersion ("2.0")]

public class DefaultController: ControllerBase

{

  stringa [] autori = nuova stringa []

  {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

  [HttpGet]

  public IEnumerable Get ()

  {

      autori di ritorno;

  }

  [HttpGet ("{id}")]

  [MapToApiVersion ("2.0")]

  stringa pubblica Get (int id)

  {

     autori di ritorno [id];

  }

}

Strategie di controllo delle versioni delle API in ASP.NET Core

Esistono diversi modi in cui è possibile eseguire la versione dell'API in ASP.NET Core. In questa sezione esploreremo ciascuno di essi.

Passa le informazioni sulla versione come parametri QueryString

In questo caso, in genere si passano le informazioni sulla versione come parte della stringa di query, come mostrato nell'URL fornito di seguito.

//localhost:25718/api/default?api-version=1.0

Passa le informazioni sulla versione nelle intestazioni HTTP

Se si desidera passare le informazioni sulla versione nelle intestazioni HTTP, è necessario impostarle nel metodo ConfigureServices come mostrato nello snippet di codice riportato di seguito.

services.AddApiVersioning (config =>

{

   config.DefaultApiVersion = new ApiVersion (1, 0);

   config.AssumeDefaultVersionWhenUnspecified = true;

   config.ReportApiVersions = true;

   config.ApiVersionReader = nuovo HeaderApiVersionReader ("api-version");

});

Una volta impostato, è possibile richiamare un metodo di azione relativo a una versione specifica dell'API, come mostrato nella Figura 3.

Passa le informazioni sulla versione nell'URL

Ancora un altro metodo per passare le informazioni sulla versione è passare le informazioni sulla versione come parte del percorso. Questo è il modo più semplice per controllare la versione dell'API, ma ci sono alcuni avvertimenti. Prima di tutto, se utilizzi questa strategia, i tuoi clienti dovranno aggiornare l'URL ogni volta che viene rilasciata una nuova versione dell'API. Di conseguenza, questo approccio infrange un principio fondamentale di REST che afferma che l'URL di una particolare risorsa non dovrebbe mai cambiare.

Per implementare questa strategia di controllo delle versioni, è necessario specificare le informazioni sul percorso nel controller come mostrato di seguito.

[Route ("api / v {version: apiVersion} / [controller]")]

Il seguente elenco di codice mostra come configurarlo nella classe del controller.

[Route ("api / v {version: apiVersion} / [controller]")]

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1")]

public class DefaultController: ControllerBase

    {

        stringa [] autori = nuova stringa []

        {"Joydip Kanjilal", "Steve Smith", "Stephen Jones"};

        [HttpGet]

        public IEnumerable Get ()

        {

            autori di ritorno;

        }

        [HttpGet ("{id}")]

        [MapToApiVersion ("2.0")]

        stringa pubblica Get (int id)

        {

            autori di ritorno [id];

        }

    }

Ecco come chiamare l'HTTP predefinito per ottenere il metodo della classe DefaultController.

//localhost:25718/api/v1.0/default

Per richiamare l'altro metodo HTTP GET, ovvero quello che accetta un parametro, specificare quanto segue nel browser Web o in un client HTTP come Postman.

//localhost:25718/api/v2.0/default/1

Ritira una o più versioni della tua API

Supponi di avere più versioni della tua API ma desideri deprecarne una o più. Puoi farlo facilmente: devi solo specificare la proprietà Deprecated della classe ApiVersionAttribute su true, come mostrato nello snippet di codice riportato di seguito.

[ApiController]

[ApiVersion ("1.0")]

[ApiVersion ("1.1", Deprecated = true)]

[ApiVersion ("2.0")]

public class DefaultController: ControllerBase

{

     // Codice usuale

}

Il controllo delle versioni delle API in ASP.NET Core ora è senza problemi grazie all'introduzione del pacchetto Microsoft.AspNetCore.Mvc.Versioning. Esistono diversi modi per aggiornare la tua API: devi solo decidere la strategia migliore in base alle tue esigenze. Puoi anche utilizzare più schemi di controllo delle versioni per la tua API. Ciò aggiunge molta flessibilità poiché i client possono scegliere uno qualsiasi degli schemi di controllo delle versioni supportati.

Come fare di più in ASP.NET Core:

  • Come utilizzare gli oggetti di trasferimento dati in ASP.NET Core 3.1
  • Come gestire gli errori 404 in ASP.NET Core MVC
  • Come usare l'inserimento delle dipendenze nei filtri di azione in ASP.NET Core 3.1
  • Come usare il modello di opzioni in ASP.NET Core
  • Come usare il routing degli endpoint in ASP.NET Core 3.0 MVC
  • Come esportare dati in Excel in ASP.NET Core 3.0
  • Come usare LoggerMessage in ASP.NET Core 3.0
  • Come inviare messaggi di posta elettronica in ASP.NET Core
  • Come registrare i dati in SQL Server in ASP.NET Core
  • Come pianificare i processi utilizzando Quartz.NET in ASP.NET Core
  • Come restituire dati dall'API Web ASP.NET Core
  • Come formattare i dati di risposta in ASP.NET Core
  • Come utilizzare un'API Web ASP.NET Core usando RestSharp
  • Come eseguire operazioni asincrone utilizzando Dapper
  • Come usare i flag di funzionalità in ASP.NET Core
  • Come utilizzare l'attributo FromServices in ASP.NET Core
  • Come lavorare con i cookie in ASP.NET Core
  • Come lavorare con file statici in ASP.NET Core
  • Come usare il middleware di riscrittura degli URL in ASP.NET Core
  • Come implementare la limitazione della velocità in ASP.NET Core
  • Come usare Azure Application Insights in ASP.NET Core
  • Utilizzo di funzionalità NLog avanzate in ASP.NET Core
  • Come gestire gli errori nell'API Web ASP.NET
  • Come implementare la gestione delle eccezioni globale in ASP.NET Core MVC
  • Come gestire i valori null in ASP.NET Core MVC
  • Controllo delle versioni avanzato nell'API Web ASP.NET Core
  • Come lavorare con i servizi di lavoro in ASP.NET Core
  • Come utilizzare l'API di protezione dei dati in ASP.NET Core
  • Come usare il middleware condizionale in ASP.NET Core
  • Come lavorare con lo stato della sessione in ASP.NET Core
  • Come scrivere controller efficienti in ASP.NET Core