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.