Route versioning in Asp.NET API

https://damienfremont.com/2017/11/23/rest-api-maturity-levels-from-0-to-5/

Context/Problem

If you are developing internal or customer facing APIs, versioning as an API capability should be at the top of your list. As your APIs evolve, and you introduce more and more features, you will most probably get into a position where your current API specification needs to change in a way that it will have breaking changes compared to existing contracts.

By the way, this topic belongs to the series to set up an Asp.NET API for production use.

1. API Route Versioning
2. Configuration Management
3. Secret Management
4. Monitoring
5. Database
6. Documentation
7. CORS
8. Request Validation
9. Global Exception Handling
10. Deploy .Net API to Azure App Service

Solution

In those situations you typically have two choices,

• Break existing contracts and as a result your current consumers.
• Introduce new routes which will keep your existing consumers happy momentarily, but it may not be a scalable solution
• Version your API, and have the same routes with new versions

As you probably won’t want to break your existing consumers, and the second option is straightforward as well, in this post we will cover API versioning.

Definition

To clarify what versioning means, lets assume we have the below route in our API which returns a list of comments:

https://api.pellerex.com/comments

After applying versioning the route should look like:

https://api.pellerex.com/v1/comments

which will enable you to have breaking changes as part of your v2 version.

Note

Configuration, plumbing and troubleshooting your software foundation take a considerable amount of time in your product development. Consider using Pellerex which is a complete foundation for your enterprise software products, providing source-included Identity and Payment functions across UI (React), API (.NET), Pipeline (Azure DevOps) and Infrastructure (Kubernetes).

The first step in applying versioning is to enable in your Web API Startup file,

Call this method in your Web API configuration method,

public void ConfigureServices(IServiceCollection services)
{
            ConfigureVersioning(services);
}

And here are the extension methods we used in the above code blocks, UseGeneralRoutePrefix,

That’s it, you now have configured versioning for your API, and can keep introducing new changes in your endpoint by bumping the version and keeping the same route name. Once you were comfortable with the new versions, ideally you should decommission the older versions and migrate all your customers to the latest version, unless you decide to have multiple versions running side-by-side.

Pellerex Foundation: For Your Next Enterprise Software

How are you building your current software today? Build everything from scratch or use a foundation to save on development time, budget and resources? For an enterprise software MVP, which might take 8–12 months with a small team, you might indeed spend 6 months on your foundation. Things like Identity, Payment, Infrastructure, DevOps, etc. they all take time, while contributing not much to your actual product. These features are needed, but they are not your differentiators.

Pellerex does just that. It provides a foundation that save you a lot development time and effort at a fraction of the cost. It gives you source-included Identity, Payment, Infrastructure, and DevOps to build Web, Api and Mobile apps all-integrated and ready-to-go on day 1.

Check out Pellerex and talk to our team today to start building your next enterprise software fast.