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:

  1. 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.
  2. If you haven’t done so already you will need to implement Attributed Routing
  3. In your Controllers folder add two new folders called v1 and v2
  4. Copy (or create) your controller files into the v1 folder.
  5. Prefix the filenames with v1_
  6. Add the version number to the Route Prefix to the controllers
     <RoutePrefix("v1/Data")>
        Public Class DataController
            Inherits ApiController
    End Class
    
  7. Start coding 🙂 Make sure you define your routes for each function with your route attribute minus the prefix:
    ' remember to remove your prefix from your routes
     <Route("GetDailyStats/{UserID}/">
     <HttpGet>
      Public Function GetDailyStats(ByVal UserID As Long) As List(Of DailyStat)
      End Function
    
So how do you version up?

When you’re ready to go to version 2 do the following:

  1. Copy your version 1 controller file into the v2 folder
  2. Rename it so it has the prefix of v2_
  3. Make sure you leave the v1_ file in the v1 folder
  4. Edit your v2_ file
    • Change the Route Prefix to v2
    • Rename the class by prefixing it with v2_
       <RoutePrefix("v2/Data")>
          Public Class v2_DataController
              Inherits ApiController
      End Class
      
  5. Make your changes and publish to your server
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

    Insert Into Users VALUES (@UserName,@Department);
    

    GOOD

    Insert Into Users (UserName,Department) VALUES (@UserName,@Department);