Asp.Net Core Versioning Web Apis Complete Guide

Step-by-Step Guide to ASP.NET Core Versioning Web APIs

1. Create a New ASP.NET Core Web API Project

First, let's create a new ASP.NET Core Web API project.

1. Open Visual Studio.
2. Select Create a new project.
3. Choose the ASP.NET Core Web API template. Click Next.
4. Configure your project by naming it and choosing a location. Click Create.
5. Choose the target framework (e.g., .NET 6.0) and click Create.

2. Install the ASP.NET Core API Versioning NuGet Package

API versioning in ASP.NET Core is not built-in, so we need to install the appropriate NuGet package.

1. In the Solution Explorer, right-click on your project and select Manage NuGet Packages.
2. Search for "Microsoft.AspNetCore.Mvc.Versioning".
3. Install the package.

3. Configure API Versioning in the Startup.cs or Program.cs

Depending on whether you're using the older Startup.cs configuration model or the newer Program.cs configuration model, the setup will differ slightly.

Using Startup.cs (for older ASP.NET Core versions <= 3.1)

1. Open Startup.cs.

2. Add the following code to the ConfigureServices method to register API versioning services:

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddControllers();
   
       // Add API Versioning
       services.AddApiVersioning(options =>
       {
           options.DefaultApiVersion = new ApiVersion(1, 0); // Default version
           options.AssumeDefaultVersionWhenUnspecified = true; // Assume default version when not specified
           options.ReportApiVersions = true; // Report supported versions
       });
   
       // Add API versioning with format versioning
       services.AddVersionedApiExplorer(options =>
       {
           options.GroupNameFormat = "'v'VVV"; // Format the version group name
           options.SubstituteApiVersionInUrl = true; // Substitute api version in the URL
       });
   }
   
   public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
   {
       if (env.IsDevelopment())
       {
           app.UseDeveloperExceptionPage();
       }
   
       app.UseRouting();
   
       app.UseEndpoints(endpoints =>
       {
           endpoints.MapControllers();
       });
   }
   

Using Program.cs (for newer ASP.NET Core versions >= 6.0)

1. Open Program.cs.

2. Add the following code to register API versioning services:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.AddControllers();
   
   // Add API Versioning
   builder.Services.AddApiVersioning(options =>
   {
       options.DefaultApiVersion = new ApiVersion(1, 0); // Default version
       options.AssumeDefaultVersionWhenUnspecified = true; // Assume default version when not specified
       options.ReportApiVersions = true; // Report supported versions
   });
   
   // Add API versioning with format versioning
   builder.Services.AddVersionedApiExplorer(options =>
   {
       options.GroupNameFormat = "'v'VVV"; // Format the version group name
       options.SubstituteApiVersionInUrl = true; // Substitute api version in the URL
   });
   
   var app = builder.Build();
   
   // Configure the HTTP request pipeline.
   if (app.Environment.IsDevelopment())
   {
       app.UseDeveloperExceptionPage();
   }
   
   app.UseHttpsRedirection();
   
   app.UseAuthorization();
   
   app.MapControllers();
   
   app.Run();
   

4. Define Versions in Your Controllers

You can version your APIs in several ways, such as URL-based versioning, query string-based versioning, or media type-based versioning. Here, we will use URL-based versioning.

Using URL-based Versioning

1. Open an existing controller (e.g., WeatherForecastController.cs) or create a new one.

2. Use the ApiVersion attribute to specify the version(s) for the controller or specific actions:

   using Microsoft.AspNetCore.Mvc;
   using System.Collections.Generic;
   
   namespace YourNamespace.Controllers
   {
       [ApiController]
       [Route("api/v{version:apiVersion}/[controller]")]
       public class WeatherForecastController : ControllerBase
       {
           [HttpGet]
           [ApiVersion("1.0")]
           public IEnumerable<string> GetV1()
           {
               return new[] { "Version 1.0 - Weather Forecast" };
           }
   
           [HttpGet]
           [ApiVersion("2.0")]
           public IEnumerable<string> GetV2()
           {
               return new[] { "Version 2.0 - Weather Forecast" };
           }
       }
   }
   

5. Test Your Versioned API

1. Run your application.
2. Use a tool like Postman or your browser to test the different versions:
   • To access Version 1: https://localhost:yourport/api/v1/weatherforecast
   • To access Version 2: https://localhost:yourport/api/v2/weatherforecast

6. Add Filters and Optional Parameters (Optional)

You can add custom filters and optional parameters to make your versioned API more flexible. Here's an example:

1. Open the WeatherForecastController.cs file.

2. Add a filter to conditionally apply versioning:

   using Microsoft.AspNetCore.Mvc;
   using System.Collections.Generic;
   
   namespace YourNamespace.Controllers
   {
       [ApiController]
       [Route("api/weatherforecast")]
       public class WeatherForecastController : ControllerBase
       {
           [HttpGet]
           [ApiVersion("1.0")]
           public IEnumerable<string> GetV1()
           {
               return new[] { "Version 1.0 - Weather Forecast" };
           }
   
           [HttpGet]
           [ApiVersion("2.0")]
           public IEnumerable<string> GetV2()
           {
               return new[] { "Version 2.0 - Weather Forecast" };
           }
       }
   }
   

   In this example, the base route does not include the version, but you can still use query string parameters to specify the version. For example:

   • Version 1: https://localhost:yourport/api/weatherforecast?api-version=1.0
   • Version 2: https://localhost:yourport/api/weatherforecast?api-version=2.0

7. Use Versioned API Explorers (Optional)

If you want to provide a UI for exploring the different versions of your API, you can use tools like Swashbuckle (Swagger) with versioned API explorers.

1. Install the Swashbuckle.AspNetCore NuGet package:

   dotnet add package Swashbuckle.AspNetCore
   

2. Configure Swagger in Program.cs or Startup.cs:

   var builder = WebApplication.CreateBuilder(args);
   
   // Add services to the container.
   builder.Services.AddControllers();
   
   // Add API Versioning
   builder.Services.AddApiVersioning(options =>
   {
       options.DefaultApiVersion = new ApiVersion(1, 0);
       options.AssumeDefaultVersionWhenUnspecified = true;
       options.ReportApiVersions = true;
   });
   
   builder.Services.AddVersionedApiExplorer(options =>
   {
       options.GroupNameFormat = "'v'VVV";
       options.SubstituteApiVersionInUrl = true;
   });
   
   // Configure Swashbuckle
   builder.Services.AddSwaggerGen(options =>
   {
       var provider = builder.Services.BuildServiceProvider().GetRequiredService<IApiVersionDescriptionProvider>();
       foreach (var description in provider.ApiVersionDescriptions)
       {
           options.SwaggerDoc(description.GroupName, new Microsoft.OpenApi.Models.OpenApiInfo
           {
               Title = $"Sample API {description.GroupName}",
               Version = description.ApiVersion.ToString()
           });
       }
   });
   
   var app = builder.Build();
   
   // Configure the HTTP request pipeline.
   if (app.Environment.IsDevelopment())
   {
       app.UseDeveloperExceptionPage();
       app.UseSwagger();
       app.UseSwaggerUI(options =>
       {
           var provider = app.Services.GetRequiredService<IApiVersionDescriptionProvider>();
           foreach (var description in provider.ApiVersionDescriptions)
           {
               options.SwaggerEndpoint($"/swagger/{description.GroupName}/swagger.json", description.GroupName.ToUpperInvariant());
           }
       });
   }
   
   app.UseHttpsRedirection();
   
   app.UseAuthorization();
   
   app.MapControllers();
   
   app.Run();
   

3. Run your application and navigate to the Swagger UI at https://localhost:yourport/swagger to see the different versions of your API.

Summary