Quando creiamo un progetto destinato a durare per tempo, avere un corretto versioning degli endpoint esposti è assolutamente cruciale per far sì che anche i client non aggiornati siano in grado di continuare a funzionare, senza il rischio di introdurre breaking change.
Una libreria che rende molto semplice la soluzione di questo problema è Asp.Versioning (https://github.com/dotnet/aspnet-api-versioning) pubblicata e manutenuta da .NET Foundation.
Per sfruttarla in un nostro progetto, non dobbiamo far altro che aggiungere il corrisponente package
dotnet add package Asp.Versioning.Http
e poi registrare il corrispondente servizio nel nostro IoC container:
public static void Main(string[] args) { var builder = WebApplication.CreateBuilder(args); builder.Services.AddApiVersioning(); // altro codice qui ...
A questo punto, possiamo finalmente iniziare a decorare tutti i nostri endpoint con la versione corrispondente:
var myVersionedApi = app.NewVersionedApi(); myVersionedApi.MapGet("/weatherforecast", (HttpContext httpContext) => { var forecast = Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)), TemperatureC = Random.Shared.Next(-20, 55), Summary = summaries[Random.Shared.Next(summaries.Length)] }) .ToArray(); return forecast; }).HasApiVersion(1.0); myVersionedApi.MapGet("/weatherforecast", (HttpContext httpContext) => { var forecast = Enumerable.Range(1, 5).Select(index => new WeatherForecast { Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)), TemperatureC = Random.Shared.Next(-20, 55), Summary = "Version 2 is always Hot!" }) .ToArray(); return forecast; }).HasApiVersion(2.0);
Nello script in alto, la differenza sostanziale che possiamo notare è che invece di registrare gli endpoint direttamente sull'app builder, abbiamo come primo passo creato una Versioned API invocando l'extension method NewVersionedApi.
A questo punto, non dobbiamo far altro che decorare i vari endpoint tramite HasApiVersion per specificarne il numero di versione.
Se proviamo a eseguire l'applicazione, in questa modalità di default, potremo cambiare il numero di versione tramite il parametro api-version in query string. La libreria ritornerà automaticamente un errore 400 (Bad Request) nel caso in cui il numero di versione sia non esistente o non supportato.
Se abbiamo introdotto il versioning "a posteriori", alcuni client legacy potrebbero non esserne a conoscenza, e in questi casi è utile indirizzarli per default alla versione 1.0:
builder.Services.AddApiVersioning(config => { config.AssumeDefaultVersionWhenUnspecified = true; config.DefaultApiVersion = new ApiVersion(1, 0); });
Asp.Versioning è una libreria estremamente versatile. Nel corso dei prossimi script daremo un'occhiata più approfondita alle sue funzionalità, partendo da come utilizzarla anche con i controller.
Commenti
Per inserire un commento, devi avere un account.
Fai il login e torna a questa pagina, oppure registrati alla nostra community.
Approfondimenti
3 metodi JavaScript che ogni applicazione web dovrebbe contenere - Parte 2
Effettuare il download di un file via FTP con la libreria FluentFTP di .NET
Utilizzare gli snapshot con Azure File shares
Utilizzare i primary constructor di C# per inizializzare le proprietà
Creare gruppi di client per Event Grid MQTT
Effettuare chiamate con versioning da Blazor ad ASP.NET Core
Gestire errori funzionali tramite exception in ASP.NET Core Web API
Utilizzare ChatGPT con Azure OpenAI
Usare Refit e Polly in Blazor per creare client affidabili e fortemente tipizzati
Effettuare lo stream della risposta in ASP.NET Core tramite IAsyncEnumerable
Eseguire attività con Azure Container Jobs
I più letti di oggi
- Evitare il flickering dei componenti nel prerender di Blazor 8
- Rilasciata la Beta 2 di Visual Studio 2008
- tra pochi minuti inizia la keynote della seconda giornata. seguila live su http://aspitalia.com/mix-11 #mix11
- .@dbochicchio ora su #aspnetcore 2 a #netconfit https://aspit.co/netconf-17
- Utilizzare angular-cli per creare una direttiva in Angular 2
- Windows Vista: il ritorno di WinFS con la beta1
- .@CristianCivera tra poco su #azure con i suoi tips&tricks per lo sviluppatore web: https://aspit.co/web15-live #aspilive
- Le novità di C# 10