9

I currently have a WCF web API that I have split into two versions. The first version runs at api.mysite.com. The second is currently not published to production.

I would like a way to publish the second API such that requests to the first version are non-interrupted. My ideas would be to add a x-api-version header and internally route the request to the designated API. If there is no header, then default to version 1. I considered adding /v1 or /v2 to the beginning of the path to delimit the version such that a request to v1 or v2 might look like:

http://api.mysite.com/v1/authentication/login
http://api.mysite.com/v2/auth/login

The only caveat is that requests without the version must work and default to version 1 (or whatever version I specify).

Although this sounds good (to me at least), I'm not sure on what the recommended way of implementing this would be. I know that I could always do some sort of reverse proxy but, I'm hoping that my solutions can be a programatic one. The less configuration that is required on the part of the server, the better. If anyone has any ideas or links to blogs/tutorials, that would be fantastic!

Thanks in advance!

  • This is how google does **v=1.0** `http://ajax.googleapis.com/ajax/services/search/web?v=1.0&rsz=8&q=stackoverflow` – L.B Jan 16 '12 at 20:19
  • I see the 'version header' and 'version URI' as similar approaches, and I would support them both. Having it in the URI is VERY helpful for developers - it makes it easy to experiment with services through a browser. I would also support a 'versionless URI' which redirects to the current 'active' version (this would usually be the latest version, but you might have scenarios where you stage new versions but dont activate them publicly). It really depends on your criteria. – Adam Jan 17 '12 at 00:17
  • After looking at implementation details, I believe that I am going to have to lean more toward the URI approach strictly due to technical ease. However, I believe that I can take this approach while still meeting my original requirement of not breaking the clients of the current API. –  Jan 17 '12 at 13:40

2 Answers2

6

Microsoft has a decent article on versioning with WCF here

Brook
  • 5,949
  • 3
  • 31
  • 45
  • This is a great article for versioning. However, I believe that it fails to meet the goals that I have for my API. Like I mentioned in a comment to Erno's answer, I want the API to be intuitive. I want to stay away from versioning specific services and/or contracts in any way that is visible to the client. I want the client to only see a versioning of the API as a whole –  Jan 17 '12 at 14:07
3

Ok, I enjoyed the answers that I have received so far (thank you both) but, it didn't quite solve my problem given the constraints and goals that I have with my API. So, I wanted to detail the solution that I have found and plan to use.

To start, I am versioning my API via the URI. This is to mean that various versions of the API will look like:

http://api.mysite.com/authentication/login
http://api.mysite.com/v1/authentication/login
http://api.mysite.com/v2/auth/login
http://api.mysite.com/v3/auth/letmeinplease
... you get the point ...

The important thing to note here is that if I do not include a version number, then I default to version 1. This will be my current setup however, it could just as easily default to the latest version, latest stable, etc.

Here we go. I created a folder in which the application will live (wwroot/api). Inside that folder I created folders for all of the versions: v1, v2, etc. Now, in IIS (7.5 for me) I created a new project which had an application root of wwroot/api/v1. Then I added each version folder (including v1) as a sub-application. This allows me to version the API via the URI (as seen above) however, there is a caveat.

Web.config inheritance can really be a pain. So, I made sure to disable it for all of my api versions. A reference on how to do this can be found here. With that exception, everything works like a charm! :-)

Community
  • 1
  • 1