.NET 5 - Use API versioning
By: Marcos Vinicios
Tags: Web Development, Dotnet, Software Development, Documentation, Csharp

.NET 5 - Use API versioning

The purpose of this article is to show some of the common strategies used on API versioning with .NET 5 API. Marcos Vinicios Follow Apr 30 · 4 min read

Versioning in .NET

Versioning is an important aspect of any mature web service. Microsoft has published REST API guidelines that require that all compliant services must support explicit versioning. This ensures that clients can rely on services to be stable over time, while still enabling service changes and new features.

What is API Versioning

Once you publish an API, it’s set in stone, the users rely on the API, but the requirements will change, and you need a way to evolve the API in order to support older versions of the service the API versioning applies.

Requirements

For building our application we’ll need a few tools:

Are you ready? Let’s go!!

1️⃣ We need to create a new project ASP.NET 5 Web Application

2️⃣ We need to add the next package:

Microsoft.AspNetCore.Mvc.Versioning

3️⃣ Now, we have the package installed, we can configure API versioning in the ConfigureServices method in the Startup class as shown below (line 4).

At this point, if we make a request this will return an error.

API Error

To solve this, we need to specify the default version when adding the API versioning service. We will use the default version (1.0) if a version is not specified in the request (if we don’t define a version, all endpoints will have the default version 1.0). The following code shows how we can do that.

If we want to let the user of the API know the supported version for the endpoint, we need to add the ReportApiVersions as shown below (line 5)

Use versions in the controller

In the next code snippet, for the WeatherForecastController we have the supported versions and we have one of them that is deprecated (1.1, as an example purpose).

If we make a request to this controller, we can see the supported versions and deprecated versions.

Supported versions and deprecated versions

Use versions in action methods

We can use the attribute MapToApiVersion, to map a specific version of an action method inside the controller. Note if we don’t assign a version to action it will be the default version assigned in the API versioning services to the container (DefaultApiVersion).

API versioning strategies do we have in .NET 5 ❓

➡️Passing version information as QueryString parameter

In this case, we can pass the version information as a query string as shown below.

➡️Passing version information in the headers

To use this strategy we need to add some configuration on the API versioning service as we can see in the next code snippet (line 6).

Now we are able to test with this strategy as shown below.

➡️Passing version information in the URL

Personally, I don’t like this approach, because it breaks a fundamental principle of REST. But to use this strategy, we need to change our controller route (line 2).

To call version 1:

To call version 2:

Conclusion

You could see how easy is to implement the API versioning with .Net 5. We can use multiple strategies we just have to decide which one is best for us.

I uploaded the code to this repository

Other Articles