API versioning in .NET application

Question

I need some clarification on API versioning in .Net Core framework.

My client want the version to be handled in Router level. Like

[Route("1/[controller]")]
public class SampleController : Controller
{
    [HttpGet("version")]
    public IActionResult GetVersion()
    {
        return Ok({"Message": "API Version 1"});
    }
}

I access this using, https://www.somedomain.com/api/1/sample/version

In IIS, I will create an application called 'api' (The path 'api' in my URL will be taken care here) under default web site and host my code here.

In order to do API versioning, what is the better way that I can follow here.

1. Can I do this?

   [ApiVersion("1")]
   [Route("{version:apiVersion}/[controller]")]
   public class SampleController : Controller
   {
       [HttpGet("version")]
       public IActionResult GetVersion()
       {
          return Ok({"Message": "API Version 1"});
       }
   
       [HttpGet("version"), MapToApiVersion("2" )]
       public IActionResult GetVersion()
       {
           return Ok({"Message": "API Version 2"});
       }
   }
   

2. Is it possible to create an application under an application in IIS. Like,

Default Web Site - > api -> 1 -> Code without API version mentioned

Default Web Site - > api -> 2 -> Updated Code without API version mentioned

3. Or can I create the versions as application in IIS and deploy the code under each applciation version. Like,

Default Web Site - > 1 -> Code without API version mentioned

Default Web Site - > 2 -> Updated Code without API version mentioned

This will end up in changing my API URL, which i don't prefer. I still want to go with the same URI.
I access this using, https://www.somedomain.com/api/1/sample/version

Please advise the best approach that I can follow here.

Answer 1

Perhaps the Map extension method of ApplicationBuilder suits your needs :

app.Map( "/1", myVersion1MappingFunction)

in the Configure method of Startup let myVersion1MappingFunction configure a separate middleware pipeline:

private static void myVersion1MappingFunction( IApplicationBuilder app)
{
   // start your special middleware for version 1
   app.UseMvc( routes =>
   {
       routes.MapRoute( ... );
   }
}

On using Map extension the fragment ("/1") is removed from HttpRequest.Path

Answer 2

If I understand you correctly are wanting to use URL Path Segment Versioning for ASP.NET Core. With that said in your examples you will NOT have separate website deployed. You have one website deployed and you do NOT create multiple applications for versioning under your default website.

With URL path segment versioning you have one web application and that application manages all routes using the ApiVersion convention. You will need to maintain the code in such a way that it can deliver old functionality with new functionality and manage all dependencies.

I would recommend reading what Microsoft has to say about this here and doing a simple proof of concept that makes sense for your implementation.

I hope this helps clear up your confusion about deploying the application multiple times for versioning.

Answer 3

In your case the best method would be to employ the versioning from the web server level so you can have different deployments and a folder per version without specifying a version in the application routing itself. (your option 2/3?)

However since IIS merely proxies requests to kestrel with .net core unlike asp.net, you'll have to setup the reverse proxy by URL/URL Re-write with ARR to different versions of the deployment.

So you could have:

1. /root/V1/
2. /root/V2/
3. etc... like you explain.

Each deployment would be running kestrel with different ports numbers and IIS would re-verse proxy to them by URL.

Here is an article on how to setup ARR with url-write. it's written with asp.net in mind, but it's the same principal:

          Reverse Proxy with URL Rewrite v2 and Application Request Routing

Answer 4

Here is a popular repository that provides a set of libraries for adding API versioning to ASP.NET Web API, OData with ASP.NET Web API, and ASP.NET Core applications.

For ASP.NET Core applications, you can install this repository's ASP.NET Core API Versioning by running the following command in the Package Manager Console:

Install-Package Microsoft.AspNetCore.Mvc.Versioning