DEV Community: Muhammad Taimur

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

Muhammad Taimur — Wed, 05 Jun 2024 12:45:18 +0000

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.

Understanding API Versioning: A Simple Guide -Part 1 : Theory

Muhammad Taimur — Wed, 05 Jun 2024 12:31:14 +0000

APIs (Application Programming Interfaces) are a crucial part of modern software development. They allow different software systems to communicate with each other, enabling the integration of various services and functionalities. But as software evolves, so do the APIs. This is where API versioning comes into play. In this article, we’ll explore what API versioning is, why it’s important, and how to implement versioning is on part 2 for this article.

What is an API?

Before diving into versioning, let’s quickly understand what an API is. An API is like a waiter in a restaurant. Just as a waiter takes your order and brings back your food from the kitchen, an API takes your request, communicates it to a server, and returns the server’s response to you.

For example, when you use a weather app, the app sends a request to a weather API, which then returns the current weather data.

Why Do We Need API Versioning?

As software and applications grow, APIs need to evolve. New features are added, old ones are modified, and sometimes deprecated. These changes can break existing integrations if not managed properly. This is where API versioning helps.

API versioning allows developers to introduce changes without disrupting the existing API consumers (clients). It helps maintain backward compatibility while rolling out improvements and new features.

How Does API Versioning Work?

API versioning involves assigning different versions to an API. Each version can have different endpoints or functionalities. Here’s a simple example:

Let’s say we have a GET /weather endpoint that returns weather data. Over time, we might want to add new data fields or change the format of the response. Instead of modifying the existing endpoint, we create a new version.

Example:

Version 1 (v1):

GET /api/v1/weather Response: { "temperature": 25, "humidity": 60 }

Version 2 (v2):

GET /api/v2/weather Response: { "temp": 25, "hum": 60, "wind_speed": 10 }

In this example, v2 introduces a new field (wind_speed) and changes the field names (temperature to temp, humidity to hum). Clients using v1 are unaffected by these changes.

Common API Versioning Strategies

Below are the 3 most common ways of API Versioning used by developers

1. URL Path Versioning

This method includes the version number in the URL path.

GET /api/v1/resource GET /api/v2/resource

2. Query Parameter Versioning

This method includes the version number as a query parameter.

GET /api/resource?version=1 GET /api/resource?version=2

3. Header Versioning

This method specifies the version number in the request header.

GET /api/resource Headers: { "API-Version": "1" }

To visualize this concept, here’s a simple wording:

Client 1 requests data using v1 endpoint.
Server responds with data in v1 format.
Client 2 requests data using v2 endpoint.
Server responds with data in v2 format.

This separation ensures that changes in v2 do not affect clients using v1. Hence both Apis works as expected.

Conclusion

API versioning is essential for maintaining the stability and reliability of APIs as they evolve. It allows developers to introduce new features and improvements without breaking existing clients. By understanding and implementing API versioning, you can ensure a smooth transition and continued compatibility for your API consumers.

Whether you choose URL path, query parameter, or header versioning, the goal remains the same: to manage changes effectively and keep your API robust and user-friendly.

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.