Structuring a Web API Stack for Versioning

Question

So I've spent the past few hours trolling through all the genuinely fantastic advice for Web API Versioning. Some of my favourites, for those having as much fun as I am, in no particular order:

Best practices for API versioning?

Versioning REST API of an ASP.NET MVC application

http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html

http://www.pluralsight.com/courses/web-api-design

http://www.pluralsight.com/courses/implementing-restful-aspdotnet-web-api

So all this advice has been very helpful in designing what is essentially the "front end" of the API. We can version the API calls... Now, I'm on to the hard part.

This is a heavily data driven application, for a company with several products (this is a new one) doing monthly releases. Some big customers who will want long-term support for API calls, some smaller customers who will want the latest releases. This we could manage with something similar to milestone/long-term-support releases of the API. Great.

But in practice this is going to get really messy, really fast. We've worked hard to separate out the layers of our own website, the beta Internal/External APIs, Repository Layers and even an SDK to boot. We separate out each release out into separate branches, but it's SAAS - we host the database. So we're not just going to be able to version the API calls - but everything underneath that. The Business Logic, Repository and the Database. Let's not even get started on Unit/Integration Testing.

So, trying and probably failing only ask one question here.

Is there a decent pattern for structuring a layered, data-driven, .NET application to cope with multiple versions?

Specifically how the database will change and how you can structure a generic stack to version it all. Some ideas I have include:

• Updating old source control branches of the stack and deploying these
• Keeping everything in the same project, but use folders/namespacing all the way down
• Splitting the projects further - so the API solution has a number of "Controller" projects, with similar concepts for the logic/repo layers

We have a fair number of developers and no matter how much ace documentation I write, realistically it will only be read when something isn't working. So ideally it needs to be as glaringly obvious as possible for developers to get this right.

Answer 1

There is no perfect solution that fits every situation, whether data-driven or not.

This is really difficult to answer. Your best bet is to use multiple versioning strategies.

For example, if the database change is simply adding a new column, older versions of the APIs can ignore the new columns.

If the database change means you have to completely re-write the repository layer, then you may want to create a new repository and new controller, instead of just versioning an API method. Then on the endpoint, you could either version the route or consumers could call the replacement endpoint.

If there are dramatic changes at all levels of the API, then versioning at IIS with a separate virtual directory may be your solution (and this may have corresponding branches or labels in source control with the intent of supporting bug/fix only).

The folders / namespacing idea can get very confusing for developers, so I would steer away from it. Routing (i.e. [Route("/v4/Orders")]) may be the better way to handle it. Again, that depends on how much code and the nature of the changes.