Versioning ASP.NET Core 2.0 Web API - Part One

In this article series, we are going to explore REST API versioning best practices. By the end of the article series, you will be able to pick the best solution for your project needs.

Problem

What is one of the best ways to implement REST API versioning in ASP.NET Core?

Solution 

There are many ways to version a REST API -

• URI-based (URL PATH SEGMENT) versioning
  
  GET /api/Items HTTP 1.1
  GET /api/v2/Items HTTP 1.1

• Header-based (HTTP Header/Custom Header) versioning
  
  GET /api/Items HTTP 1.1
  GET /api/Items HTTP 1.1
  ApiVersion: 2

• Query String Parameter Versioning
  
  /api/hi?api-version=2.0

• Media type-based versioning
  
  GET /api/Items HTTP 1.1
  Accept: application/vnd.smartit.esale.webapi+json
  GET /api/Items HTTP 1.1
  Accept: application/vnd.smartit.esale webapi-v2+json 

One of the best ways to implement the versioning in ASP.NET Core Web API is the URI-based versioning with using different namespaces on the Controllers.

• GET /api/v1/Hi
• GET /api/v2/Hi

In this step by step tutorial, I will demonstrate how to version a Web API in ASP.NET Core using the URI-based method with different namespaces on the Controllers.

Why you would want to choose this approach 

Let us look at the advantages and disadvantages of this approach.

PROS of URI-based API versioning

GET /api/v1/Hi
GET /api/v2/Hi

• Most common method that is currently in use by APIs today
• Easy to implement with the code
• It is easy to consume
• It allows exploring different versions with just a browser.
• Fast performance, no overhead of search or switch statement needed.
• Can be added to any old, not versioned or versioned REST API project
• No extra configuration needed
• Extremely easy to test

CONS

• It disrupts the RESTful compliance: URIs should represent the resources and not versions (one URI: one resource/resource version)

Steps to complete REST API versioning for this example

Step 1 - Download the sample project from website

Step 2- Add API Version 1 Controller

Step 3- Add API Version 2 Controller

Step 4- Test and verify the v1 and v2 of APIs

Step 1- Download the sample project 

Go to

http://smartitcodeacademy2018.azurewebsites.net

• Select Category as Article.
• Item as API Versioning-Web API Tutorial

Compile and run the sample project.

Add a new HiController.cs under the Controllers folder.

For simplicity of illustration, the sample controller will only have a single get method, as all the other actions will behave identically. 

Replace the HiController code with the below one.

Listing

HiController.cs (Simplifies for easy illustration and learning),

using Microsoft.AspNetCore.Mvc;

namespace SmartIT.V1Hi.Controllers
{

public class HiController : Controller
   {
      [Route("~/api/v1/Hi")] // Attribute routing
      [HttpGet]
      public IActionResult Get() => Content("Hi Version 1");
   }
}

namespace SmartIT.V2Hi.Controllers
{
   public class HiController : Controller
   {
      [Route("~/api/v2/Hi")]// Attribute routing
      [HttpGet]
      public IActionResult Get() => Content("Hi Version 2");
   }
}

Note

In real-world projects, this controller will be in their own folder with separate files.

We created the HiController with an attribute routing  /api/v1/Hi HTTP Get method with SmartIT.V1Hi.Controllers Namespace.

Listing

HiController  for V1 

// api/v1/h1
namespace SmartIT.V1Hi.Controllers
{

public class HiController : Controller
   {
      [Route("~/api/v1/Hi")] // Attribute routing
      [HttpGet]
      public IActionResult Get() => Content("Hi Version 1");
   }
}

We created the HiController with an attribute routing  /api/v2/Hi HTTP Get method with SmartIT.V2Hi.Controllers Namespace.

Listing - HiController  for V2

// api/v2/h1
namespace SmartIT.V2Hi.Controllers
{
   public class HiController : Controller
   {
      [Route("~/api/v2/Hi")]// Attribute routing
      [HttpGet]
      public IActionResult Get() => Content("Hi Version 2");
   }
}

NOTE

The only difference between the two Controllers is route attribute and the content of the Get method. 

Compile and run the project.

Route	Namespace	Content
[Route("~/api/v1/Hi")]	SmartIT.V1Hi.Controllers	Hi Version 1
[Route("~/api/v2/Hi")]	SmartIT.V2Hi.Controllers	Hi Version 2

Also, don't worry. You can use namespaces to have multiple HiControllers without having to have any number in the class names. 

Compile and run the project.

Go to the /api/v1/Hi:  http://localhost:58570/api/v1/hi

It displays “Hi Version 1”

Go to the /api/v2/Hi:  http://localhost:58570/api/v2/hi

It displays “Hi Version 2”

Swagger is pre-set in this project. To see APIs in swagger, go to the swagger URI.

http://localhost:58570/swagger/

Click on GET /api/v2/hi 

Summary 

In PART 1, we leaned the simplified way to version REST Web API with using different namespaces on the Controllers.  In part 2 of this article, I will demonstrate a real-world example of how to version URI-based versioning and adding API version number to the response header.

Download source code.

References

• https://www.amazon.com/John-Kocer/e/B0779Q6VV3/ref=dp_byline_cont_ebooks_1
• Professional Entity Framework Core 2.0 & 6.x with Examples
• JumpStart ASP.NET Core 2.0 and jQuery with Examples
• Angular 5.0: ASP.NET Core 2.0 and Web API with Examples
• Top 10 Interview Questions for Software Developers

Thank you for reading this article. You may be interested in reading the below Training articles too.

• How To Use Postman With ASP.NET Core Web API Testing
• How To Use Swagger With ASP.NET Core Web APIs
• How To Write Simple To-do CRUD ASP.NET MVC Application
• How To Create To-Do CRUD Operation With ASP.NET MVC Core, Angular 4.0
• Getting Started With ASP.NET Core And jQuery CRUD Using WEB API