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
Limitare le richieste lato server con l'interactive routing di Blazor 8
Implementare il throttling in ASP.NET Core
Miglioramenti nelle performance di Angular 16
Eseguire query manipolando le liste contenute in un oggetto mappato verso una colonna JSON
Sfruttare lo streaming di una chiamata Http da Blazor
Usare una container image come runner di GitHub Actions
Effettuare lo stream della risposta in ASP.NET Core tramite IAsyncEnumerable
Short-circuiting della Pipeline in ASP.NET Core
Creare form tipizzati con Angular
Gestire errori funzionali tramite exception in ASP.NET Core Web API
Recuperare un elemento inserito nella cache del browser tramite API JavaScript
Creazione di componenti personalizzati in React.js con Tailwind CSS