Quick and Easy API Versioning

There’s many different ways to handle API versioning. Some require a bit of set up but add lots of safe guards and help for you as a developer.

For me I prefer what I call the set and forget method. The idea is that once you have decided to move on to a new version of your API you want to leave the old one as it is and just work on the new one without affecting any users who are still mapped to the old version.

I recommend implementing versioning at the start of your development but it’s pretty easy to convert your existing code. Let’s dive in on how it all works:

With a standard WebAPI you will have one or more controllers in your Controllers folder. For this case scenario we are going to pretend we have DataController.vb and UserController.vb.

So what are we actually doing here?

As far as the server is concerned we are just adding a new controller. Because you have essentially copied and pasted your v1 controller into v2 the two controllers will be exactly the same. Any existing client apps that connect to your v1 controller will not be affected. You can now start developing your client app to connect to v2 instead of v1 without breaking anything.

When should you version up?

I version up when I’m starting a new major version of my client app. Typically version 2 of my app will connect to v2 of my API. I use this method to ensure any V1 clients will not be affected. It also means I can work on V2 without having to build a whole new web service and easily implement shared code and classes from V1.
This method isn’t really the best one for granular updates (hence why I don’t have v1.1, v1.2 etc). If you need this approach I would recommend looking at a more purist and traditional way of API versioning. This NuGet package will do a lot of the work for you: https://www.nuget.org/packages/SDammann.WebApi.Versioning

What can go wrong?

If you keep your custom class objects,enums, properties etc in a separate file you should version control these too. You may not want to add in or remove a property that will break V1 code.

Make sure your database structure changes won’t affect v1 clients. Adding new fields to a datatable is a good example. Make sure all of your INSERT Statements specify the field names properly:BAD