August 19, 2003

Web Services and Versioning

Radovan talks about Typing again, as a follow up on his entry on Versioning and Web services, inspired by watching the Microsoft video starring Doug Purdy. I finally found some time to watch it myself, and here are some thoughts about it ...

First of all, I really like Doug - for a knight of the Evil Empire, he shows a great sense of humour. I also love the Mac OS X poster on his wall - a sure sign of technical competence, expressed by his choice of operating system.

Doug presents four different alteratives about how to implement loosely coupled, resilient Web services:

1. Use an XSD Any type and just stream an object in its binary form
2. Use an XSD string and pass around the object's XML represenation in string form
3. Use an open content model and have the web method strongly typed (in his example, with "Person" appearing in the method signature)
4. Pass a DOM object though the interface

Doug's recommendation is to use the open content model variant, and it immediately seemed to make sense to me - at least as far as I understand it. That is because the other three options are clearly bad, because

• just streaming a binary representation of an object through SOAP bypasses all of XML's validation features, seems a totally inappropriate usage of the SOAP stack, and, first and foremost, totally kills interoperability;
• Using a string to pass around XML is marginally better, but still requires programmers on both the client and server side to work directly with XML - something that should be left to the runtime (after all, that's what one has it for, right?);
• passing a DOM is a bit better, but still removes the ability for the SOAP stack's tools to generate any meaningful client or server side skeleton code for you.

In addition, all of these three methods take meaning out of the XML Schema that is being generated (as part of or included from the WSDL). IMHO, one of the cool things about Web services is that you can see what the services do by looking at the WSDL. This is also key in enabling tools like Microsoft's InfoPath to create anything meaningful from the WSDL definition.

So there is a lot to be said for having strongly typed methods in your service implementation - the XSD will reflect the actual content types, tools will be able to generate a meaningful client and server ... of course the basic premise of Doug's presentation is to show how to come around the one major problem with this approach: Once you change your method signatures, you have to recompile the client.

So the concept of using an open content model seems to be a great way to address this. However, I don't think Doug's example is very good, and I'm also not sure how this can be translated into other SOAP stacks and programming languages.

The problem with Doug's example is that I don't think it really illustrates the problem, which I understand ot be this:

Assume I have a method like this:

  public void add(Person p);

with Person containing some fields in version 1:

public class Person {
  public String version;
  public String name;
  public int age;
}

and an additional field in version 2:

public class Person {
  public String version;
  public String name;
  public int age;
  public String address;
}

then what I'll want is to be able to have two different XML Schema definitions for the two versions. This way, I can publish version 1 at some point in time, and have consumers generate client implementations against that schema. Now the key is that once I upgrade the server to version 2, and publish the schema, I want both version 2 clients to be able to generate a client for version 2, as well as version 1 clients to be able to happily continue sending me version 1 persons.

I don't see any clear way how to achieve this. I'll need to play around with some code before I start making wild guesses ...

Stefan went into details of the Doug's movie. I think that the suggested way to survive the evolution is to define one schema for Person with open backdoors (anyElements). Such schema survives evolution since all element additions are compatible with...

Read more in Web Services and Versioning III »

Have you ever played with the code and found a way to have "version 1 clients to be able to happily continue sending me version 1 persons"?

Thanks! I am trying to solve that problem right now and I can't find much help. I must be searching with the wrong key word.