Mastering API Versioning in ASP.NET C# in minimal api: Best Practices and Tips

Let’s dive into some code snippets and examples to better understand API versioning in Minimal API:

Versioning with URI:

In this example, we will use URI versioning to version our API. We will create a simple endpoint that returns a list of products. We will version the API by adding “v1" to the URI.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

app.MapGet("/v1/products", async context =>
{
    var products = new List<string>() { "Product 1", "Product 2", "Product 3" };
    await context.Response.WriteAsJsonAsync(products);
});

app.Run();

In this code, we are using the MapGet method to map a GET request to “/v1/products”. The response is a list of three products in JSON format. We are also using the Swagger API documentation tool to document our API.

Versioning with media type:

In this example, we will use media type versioning to version our API. We will create a simple endpoint that returns a list of products. We will version the API by adding a version parameter to the media type.

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

app.UseSwagger();
app.UseSwaggerUI();

app.MapGet("/products", async context =>
{
    var products = new List<string>() { "Product 1", "Product 2", "Product 3" };
    var response = new ObjectResult(products);

    if (context.Request.Headers.ContainsKey("Accept") &&
        context.Request.Headers["Accept"].Contains("application/vnd.example.v1+json"))
    {
        response.ContentTypes.Add("application/vnd.example.v1+json");
    }
    else
    {
        response.ContentTypes.Add("application/vnd.example.v2+json");
    }

    await response.ExecuteResultAsync(new ActionContext() { HttpContext = context });
});

app.Run();

In this code, we are using the MapGet method to map a GET request to “/products”. The response is a list of three products in JSON format. We are using the ObjectResult class to create the response object. We are then checking the Accept header of the request to determine the version of the API to return. If the Accept header contains “application/vnd.example.v1+json”, we return version 1 of the API. Otherwise, we return version 2. We are using the ContentTypes property of the ObjectResult class to set the media type of the response. We are also using the Swagger API documentation tool to document our API.

Conclusion:

In this blog, we explored API versioning in Minimal API. We covered the best practices and tips for versioning your APIs, including choosing a versioning scheme, using semantic versioning, and versioning with URI and media type. We also provided code snippets and examples to help you get started with versioning your APIs in Minimal API.