How to do Web API versioning with URI in C# ASP.NET WebAPI?

Once a Web API service is made public, different client applications start using our Web API services. As the business grows and requirements change, we may have to change the services as well, but the changes to the services should be done in a way that does not break any existing client applications.

This is when Web API versioning helps. We keep the existing services as is, so we are not breaking the existing client applications, and develop a new version of the service that new client applications can start using.

One of the most common approaches to implement versioning is by using URI-based versioning, where the version number is included directly in the URL path. This approach is explicit, easy to understand, and allows different versions to coexist seamlessly.

URI Versioning Approach

In URI versioning, the version number is embedded in the URL path, typically as /api/v1/, /api/v2/, etc. This approach uses attribute routing to define specific routes for each version.

Example: Version 1 Implementation

Let us consider a version 1 (V1) of student controller which has basic student information −

Student Model V1

using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace DemoWebApplication.Models
{
    public class StudentV1
    {
        public int Id { get; set; }
        public string Name { get; set; }
    }
}

Student Controller V1

using DemoWebApplication.Models;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace DemoWebApplication.Controllers
{
    public class StudentV1Controller : ApiController
    {
        List<StudentV1> students = new List<StudentV1>
        {
            new StudentV1
            {
                Id = 1,
                Name = "Mark"
            },
            new StudentV1
            {
                Id = 2,
                Name = "John"
            }
        };

        [Route("api/v1/students")]
        public IEnumerable<StudentV1> Get()
        {
            return students;
        }

        [Route("api/v1/students/{id}")]
        public StudentV1 Get(int id)
        {
            var studentForId = students.FirstOrDefault(x => x.Id == id);
            return studentForId;
        }
    }
}

In the above example, we have used Attribute Routing to implement the versioning. The [Route] attribute explicitly defines the URI pattern including the version number.

Example: Version 2 Implementation

Now let us say the business has proposed a new change where the student name should be split into first name and last name, but existing users should still use Version 1. In this case, we introduce Version 2 (V2) −

Student Model V2

namespace DemoWebApplication.Models
{
    public class StudentV2
    {
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
    }
}

Student Controller V2

using DemoWebApplication.Models;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace DemoWebApplication.Controllers
{
    public class StudentV2Controller : ApiController
    {
        List<StudentV2> students = new List<StudentV2>
        {
            new StudentV2
            {
                Id = 1,
                FirstName = "Roger",
                LastName = "Federer"
            },
            new StudentV2
            {
                Id = 2,
                FirstName = "Tom",
                LastName = "Bruce"
            }
        };

        [Route("api/v2/students")]
        public IEnumerable<StudentV2> Get()
        {
            return students;
        }

        [Route("api/v2/students/{id}")]
        public StudentV2 Get(int id)
        {
            var studentForId = students.FirstOrDefault(x => x.Id == id);
            return studentForId;
        }
    }
}

How It Works

When a client makes a request to /api/v1/students, it gets routed to the StudentV1Controller and returns the V1 model with a single Name property. When a client requests /api/v2/students, it gets routed to the StudentV2Controller and returns the V2 model with separate FirstName and LastName properties.

Benefits of URI Versioning

Conclusion

URI-based versioning in ASP.NET Web API provides a clean and explicit way to maintain multiple versions of your API. By using attribute routing with version numbers in the URL path, you can ensure backward compatibility while introducing new features, allowing existing clients to continue functioning while new clients can adopt enhanced versions.