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
Eseguire un metodo asincrono dopo il set di una proprietà in Blazor 8
Creare un'applicazione React e configurare Tailwind CSS
Gestione dell'annidamento delle regole dei layer in CSS
Utilizzare il trigger SQL con le Azure Function
Come migrare da una form non tipizzata a una form tipizzata in Angular
Generare un hash con SHA-3 in .NET
Registrare servizi multipli tramite chiavi in ASP.NET Core 8
Eseguire query manipolando le liste contenute in un oggetto mappato verso una colonna JSON
Sfruttare MQTT in cloud e in edge con Azure Event Grid
Come EF 8 ha ottimizzato le query che usano il metodo Contains
Usare le navigation property in QuickGrid di Blazor
Utilizzare la versione generica di EntityTypeConfiguration in Entity Framework Core