Introduction to API Versioning

25 januari 2021 om 10:00 by ParTech Media - Post a comment

Changes are inevitable and so are software updates. But, not everyone is interested in such changes, especially some of the users of the software. For example, let us assume Partech develops a product. For ease of understanding, let's assume it is for doing basic math calculations. They make this available as an API to their customers.

Over the next few months, they constantly update the software and even make a major software upgrade with a lot of additional features. But not all their customers want to consume the latest API with the new features. Some want just the old API without the new features because they don’t have any use for the new features and it will just complicate their operations. Hosting multiple APIs, one with existing features and another one with new features is out of the question for Partech. This will be a costly and cumbersome process to deploy and maintain.

So, what is the solution? What could the developers possibly do to provide support for the existing features as well as for the new features individually? The answer is API Versioning which the developers can take advantage of and deliver their product with both the new and existing features. In this post, we are going to see what is API Versioning and every other aspect of it.

Table of contents

  1. What is API Versioning?
  2. When to version an API?
  3. Different methods of achieving API Versioning in C#
  4. Implementing API Versioning in C#
  5. Wrapping up

What is API Versioning?

Web API Versioning comes in handy when the business requirements grow and also when the software changes drastically over time.

As there are chances that the API can be consumed by multiple clients at any given time, versioning of APIs is essential to have uninterrupted service for old clients and also to support backward compatibility.

When to version an API?

Whenever a breaking change is made, then it is advised to have versioning of the API. Below are a few changes which are considered as breaking -

  1. Response data format changes for more than one call.
  2. Change in response type.
  3. Removal of available functionality.

Different methods of achieving API Versioning in C#

Web versioning can be achieved in multiple ways in C#. Let's see the different techniques in this section.

Versioning using URI

In this method, the API URI is changed and the version value is added as a part of it. Let's understand it with an example.

Imagine a controller in an API that is designed to return a student's first name, department, and the year of joining. Now, some clients require additional information along with these, such as last name, age, current year, year of passing out. Now if we see, the details that are requested in the second are an extended version of the first.

To make both the request and response live for the clients, the version number will be added as an attribute in the URI, by which clients can consume the required version and get the required data.

Example - https://www.abc.com/api/v2/getstudentdata

Versioning using QueryString

Similar to the versioning using URI, instead of adding the version as a part of the URI, the details of the versioning will be added as a part of QueryString.

To achieve this, a custom selectcontroller needs to be created, to catch the incoming request and map it to the right controller based on the passed version.

Example - https://www.abc.com/api/getstudentdata?version=2

Versioning with Custom headers

In the header section of the request, custom headers will be introduced and the value of the header will be the version number that the user wants to consume.

To read the version value from the header, changes have to be made in the configuration services method present in the startup.cs file.

services.AddApiVersioning(config =>

{

  config.DefaultApiVersion = new ApiVersion(1, 0);

  config.AssumeDefaultVersionWhenUnspecified = true;

  config.ReportApiVersions = true;

  config.ApiVersionReader = new HeaderApiVersionReader("version");

});

On adding the above lines of code, the user has to call the API with the header "version" and its value to call a specific version number.

Similar to adding the version information in the custom header fields, the version number can be sent in the ‘Accept’ header field.

Example - ‘Accept’ ‘application/json; version=2’

Implementing API Versioning in C#

In this section, let's see how to create an API and how to make use of the versioning feature in C#.

Step 1

Create an ASP.Net Core based Web API and provide a name for the solution.

After providing the name, choose API as the project template to create.

On clicking Create, the structure of the solution appears as below.

Step 2

Once the structure is ready, right-click on the solution and select 'Manage NuGet Packages for Solution'.

In the NuGet package manager window, search for 'versioning' and look for the package 'Microsoft.AspNetCore.Mvc.Versioning', and select 'Install'.

Step 3

After installing the package, open the startup.cs file, and under the ConfigureServices method, add the below lines of code.

services.AddApiVersioning(config =>

{

  config.DefaultApiVersion = new ApiVersion(1, 0);

  config.AssumeDefaultVersionWhenUnspecified = config.ReportApiVersions = true;

});

Step 4

Open the weatherforecastcontroller file, in the shorthand attribute section of the controller, add the below API versions.

[ApiVersion("1.0")]

[ApiVersion("2.0")]

Step 5

Add the below action method in the weatherforecastcontroller class, this method can be called with v2.0 in the URL and it returns the requested data.

To deprecate a version of API, you just need to specify the version in the below manner.

[ApiVersion("1.1", Deprecated = true)]

Wrapping up

In the real world, an API is never going to remain the same; either new changes come up or the existing ones go away. In both cases, versioning can be used to handle the upgrade and the deprecation of changes in an efficient way. But remember, before each version upgrade/deprecation, it's the responsibility of the organization to communicate the changes to the clients by providing the relevant difference.