Question

I was just looking to develop .NET WCF API. We may need to frequently update APIs.

How to manage multiple versions of API deployment?

Answer 1

Versioning your services is a huge topic with many considerations and guidelines.

For a start, there are different classes of changes you can make; fully-breaking, semi-breaking, and non-breaking.

Non-breaking changes (no change needed to existing clients) include:

• changing the internal implementation of the service while keeping the exposed contract unchanged
• changing the contract types in a way which does not break clients, for example, by adding fields to your operation return types (most serializers will raise an event rather than throw an exception when encountering an unexpected field on deserialization)
• polymorphically exposing new types (using ServiceKnownType attribute)
• changing the instance management settings of the service (per-call to singleton, sessionless to sessionful etc, although sometimes this will require configuration or even code changes)

Semi-breaking changes (usually can be configured on the client) inlcude:

• changing the location of a service
• changing the transport type a service is exposed across (although changing from a bi-directional to a uni-directional transport – eg http to msmq – can be a fully-breaking change)
• changing the availability of the service (through use of service windows etc)

Fully-breaking changes (need new version of the client) include:

• changing service operation signatures
• changing exposed types in a breaking manner (removing fields, etc)

When you are going to make a semi or fully breaking change, you should evaluate the best way of doing this. Do you force all your clients to upgrade to use the new version, or do you co-host both versions of the service at different endpoints? If you choose the latter then how will you control and manage the propagation of different versionning dependencies which this may introduce?

Taken to an extreme, you could look into dynamic endpoint resolution, whereby the client resolves the suitable endpoint to call at runtime using some kind of resolver service.

There’s good reading about this here:
http://msdn.microsoft.com/en-us/library/ms731060.aspx