How to version Commands?

[BrettJaner]

Hey Steven,

I think I'm having a problem versioning my commands. I currently have two UI projects (Desktop & Web) sharing the same command/query handler web service. The command/query contracts are deployed to the Desktop and Web UI projects via NuGet, so they can choose when to upgrade separately. When I add a new property to a command, I currently do no tracking of this version change in the command type itself.
The new command property will generally be mapped to an entity property and stored in the database. If you are using an older version of the contract, the web service will default the new property value to something during Json deserialization. So if the Web UI project decides to use the new version and the Desktop project does not, the command coming from the Desktop project could overwrite the value of the new command property with the default value. I think what'd I'd like to have happen is if you are using an older version of the contract, these defaulted values are ignored during entity mapping. I'm wondering if you ever came across this issue? Or have any advice on how to solve it?

Thanks for any advice,
Brett

[dotnetjunkie]

Hi Brett,

Versioning is always difficult. Whenever possible, I try to roll out server and client at the same time, which prevents this problem. This is obviously not always possible. Good example is when working with mobile apps. It takes time before your new mobile version is approached by Google and Apple and even if they have, it could take ages for users to upgrade to a new version.

So in general, additions to commands should be optional. This means that the client should be able to send the old version of the command that misses this this information, should still be accepted. On the server side you will have to do the correct handling. This might mean that you use some default value in case it is missing. This might mean that you can't do auto-mapping from the command to your entity.

In your particular case, you might want to distinct between a value that is deliberately left blank by the client that uses a V2 of the contract or between a missing value caused by a client that uses V1 of the contract. Another option is to create a new commandV2 that inherits from the the old command. This is a quite effective way of versioning.

[BrettJaner]

Sounds about right. I was hoping there was some secret sauce I was unaware of that'd make this easy. Thanks for your reply.

[barik-jyoti]

I have landed up in a situation where I must do URL based versioning such as "../api/v1/.."as per client requirement. But I am not very sure if this can be achievable in this approach. Any suggestions?

[dotnetjunkie]

I see no reason why versioning wouldn't work. You can have different routings per version, which each version having its own delegating handler with its own list of commands and queries. You could even share commands and queries over versions in case their shape or behavior haven't changed between versions. That gives you maximum reusability.

[dotnetjunkie]

But TBH, unless you need to support WCF or another SOAP based API with a very strict contract scheme, I would advise against doing /v1 /v2 altogether, since they are always more painful to maintain unless the new version is a complete rewrite (i.e. a totally different API) of the old one.

[barik-jyoti]

Thanks for your reply.

As far as I can see there won't be any situation where a complete rewrite would be necessary. However, the client just wants to keep the option open just in case. So going by your previous suggestion, I would try and create one end point(query/command) to check and prove the feasibility.

Thanks.