Best Practices and How to support different versions of REST APIs in C# wrapper on client-side

Question

I have written a C# wrapper to support our company project's REST APIs. However, these APIs are changing now - in terms on URL (may introduce version number in URL) and data objects it expects and returns back.

I would like to know what would be the best practice on supporting different versions of REST APIs in my c# wrapper.

And how should I do it - in terms of code design and class definitions - so that one wrapper can work seamlessly with different versions of API - and it should be extensible also - so that any newer version of APIs in future can also be easily supported.

The c# wrapper I have written is consuming our web service APIs. I am already using RestSharp client to consume our web service APIs in c# wrapper.

Haphazardly

Please clarify - are you consuming REST APIs, or producing them? If producing them, what framework are you using (WebAPI, ServiceStack, WCF)? If consuming them, please post sample code of how you are consuming currently. Thanks. – Disorganize

Also, while it may not directly answer your question about versioning, you should consider using RestSharp for consumption restsharp.org – Disorganize

The c# wrapper I have written is consuming our web service APIs. I am already using RestSharp client to consume our web service APIs in c# wrapper. – Haphazardly

Answer 1

There's a subtle weirdness to what you are asking. Let me reiterate what you have stated:

1) There are multiple versions of the same service at your organization. Perhaps they are established like Bob suggested, /current/api... /v1/api... /v2/api... etc. Or perhaps some other pattern.

2) You want a single C# library to be aware of each of the different versions.

It's this second part that is strange. Normally a client-side library would target a specific version only. It would be the server's responsibility to make sure that new versions of a service were either backwards compatible with old versions, or isolated on a new url.

Ask yourself this - if you were to go ahead and build this library that was aware of multiple versions of the same service, how would it look to the consumers of your library? Would they have to specifically tell you which version to use? That's not a concern I would expect to have to be aware of.

var client = new MyClient();
client.DoSomething();   // Makes sense    
client.DoSomethingV2(); // Huh?

Disorganize

Creating new function for each API of newer version would be difficult - as there are almost 160 APIs. I want to make design generic such that I can use same function (as endpoint is not changing) to either return V1 DTO or V2 DTO – Haphazardly

That would break compatibility with any clients that were not updated. You should be versioning the server side, not the client side. – Disorganize

Have a look at this article: mnot.net/blog/2011/10/25/web_api_versioning_smackdown He does talk about never breaking the client, which was my main point. He also talks against using URI as means of versioning, and suggests two alternatives: 1) Putting the version of the client as part of the request header and making sure the server understands all versions, or 2) Self-discovery of services via HATEOAS approach. I'm not sure if WebAPI can cleanly do HATEOAS, so I would go with the first option. Either way, the client should only ever be aware of one version at a time. – Disorganize

I agree that client should ONLY be aware of one version only. Also, we are using version number in URL. Beside, version number, URL is same in both version - just returns different object. Now, my API wrapper is used for internal testing of APIs as well. So, I would like to design wrapper such that, I can call API for any version, and test APIs for backward compatibility as well using same wrapper. – Haphazardly

Answer 2

Set up API versions, keep your current version as say version 1 and then add a v2 something like

/current/api?id=x....
/version2/api?id=x...

This allows you to update your api to support new functionality, and then you can set up a sunset plan for your out dated versions.

This way you can let your customers move over to your new system without it being an emergency.

Tallman

He's asking about the client side, not the server. – Disorganize