Understanding API Versioning: A Simple Guide -Part 1 : Implementation using C#

In pervious article I discussed the Theory of API Versioning, In this article I will explain how to implement API versioning.
Used technology C# and .Net

Below is a C# code example that demonstrates how to implement API versioning using .NET Core. This example uses URL path versioning, where the version number is included in the URL path.

To start Open Visual Studio and create a new ASP.Net Core Web API project. Once the project is setup install the necessary package from Nuget Packages.
Microsoft.AspNetCore.Mvc.Versioning

Your .csporj file look like this:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Versioning" Version="5.0.0" />
  </ItemGroup>

</Project>

Next, let's set up the API in your ASP.NET Core project:

Startup.cs: Configure API versioning in your startup file

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

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddControllers();
        services.AddApiVersioning(config =>
        {
            // Specify the default API Version
            config.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0);
            config.AssumeDefaultVersionWhenUnspecified = true;
            config.ReportApiVersions = true;

            // Versioning strategy: URL path
            config.ApiVersionReader = new Microsoft.AspNetCore.Mvc.Versioning.UrlSegmentApiVersionReader();
        });
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        if (env.IsDevelopment())
        {
            app.UseDeveloperExceptionPage();
        }

        app.UseHttpsRedirection();
        app.UseRouting();
        app.UseAuthorization();
        app.UseEndpoints(endpoints =>
        {
            endpoints.MapControllers();
        });
    }
}

WeatherController.cs: Define your versioned API controllers.

using Microsoft.AspNetCore.Mvc;

namespace VersioningExample.Controllers
{
    // v1 Controller
    [ApiController]
    [Route("api/v{version:apiVersion}/weather")]
    [ApiVersion("1.0")]
    public class WeatherV1Controller : ControllerBase
    {
        [HttpGet]
        public IActionResult Get()
        {
            var weatherData = new
            {
                temperature = 25,
                humidity = 60
            };
            return Ok(weatherData);
        }
    }

    // v2 Controller
    [ApiController]
    [Route("api/v{version:apiVersion}/weather")]
    [ApiVersion("2.0")]
    public class WeatherV2Controller : ControllerBase
    {
        [HttpGet]
        public IActionResult Get()
        {
            var weatherData = new
            {
                temp = 25,
                hum = 60,
                wind_speed = 10
            };
            return Ok(weatherData);
        }
    }
}

Program.cs: The entry point of your application.

using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Hosting;

public class Program
{
    public static void Main(string[] args)
    {
        CreateHostBuilder(args).Build().Run();
    }

    public static IHostBuilder CreateHostBuilder(string[] args) =>
        Host.CreateDefaultBuilder(args)
            .ConfigureWebHostDefaults(webBuilder =>
            {
                webBuilder.UseStartup<Startup>();
            });
}

In this setup:

• We configured API versioning in the Startup.cs file.
• We created two controllers, WeatherV1Controller and WeatherV2Controller, to handle different versions of the weather endpoint.
• Each controller has its own version-specific route and response format.

Now, you can access the different versions of the API by making requests to:

• GET /api/v1/weather for version 1
• GET /api/v2/weather for version 2

This ensures that changes in version 2 do not affect the clients using version 1, demonstrating the concept of API versioning.

Happy coding!

Feel free to ask questions or share your thoughts in the comments below! If you found this article helpful, don’t forget to like and share it.