Don Smith has a post entitled One parameter to rule them all: Part 2 where he writes

In my post yesterday, I recommended that Web Service operations should only have a single input parameter rather than multiple for the sake of versioning.
...
Suppose we want to send version information to the operation. In the example above, there's nowhere for it to go. "Why would we want to send version information to the operation?" Because as we version the operation, we should include version information so it's obvious what changed in each version. We can't get that information by simply adding new parameters to the method signature. I'm not going to go into it here (I will in my article) but there is a approach Doug talks about here about how to version datatypes that contain this version metadata. By using a single uber-parameter, we can include the traditional parameters as well as any metadata we need to send like version infomation. Then, instead of having to check for nulls, we can switch on the version metadata.

To me this seems to imply a simplistic view of the problems inherent in versioning XML Web Service end points and also pushes unnecessary API clutter on users of the end point. So imagine that in v1 of the end point, the GetTemp method takes a city and zip code then in v2 an optional zip code is added. To me I'd rather have developers know they can either call

MyService.GetTemp("Redmond", "WA");
MyService.GetTemp("Redmond", "WA", "98052"):

instead of

MyService.GetTemp(new TemperatureRequest("1.0", "Redmond", "WA"));
MyService.GetTemp(new TemperatureRequest("2.0", "Redmond", "WA", "98052"));

For one, the latter is less straightforward than the former. Also the developer has to know how to manage interdependencies between properties of the TemperatureRequest that are set if there are any that are mutually exclusive, know which properties are required and whether to initialize primitive values in the object to defaults without any help from the API. Of course, all this will be in the documentation but APIs should be designed so their behavior is intuiive not so that one is required to read all the documentation before one can get things done.

The other reason I like the former is that it carries the impression that the XML Web Service end point is unchanging while the latter does not. This is not really a tachnical reason but it makes it less likely that the designer of the service will change the behavior of that particular method at specific end point if its contract never changes.

My dayjob now involves designing XML Web Service end points so you'll probably start seeing more XML Web Services related posts from me.


 

Tuesday, November 30, 2004 1:11:32 PM (GMT Standard Time, UTC+00:00)
Yeah, that was always weird to me - that one parameter principle. What's wrong with ordinar bullet-proof method overloading?
Tuesday, November 30, 2004 2:57:08 PM (GMT Standard Time, UTC+00:00)
Here again I think we catch a hint Object vs. Message debate - the former technique looking rather OO and the latter being more message-like. That said, which technique is more "straightforward" really depends on the perspective that is taken.

As well, I would say that managing the interdependencies/constraints is a necessary cost in either case. More that just the right message signature is needed to validate a request/call - otherwise, who would ever need to write precondition checks and what use would argument exceptions be?
Aaron F.
Friday, December 3, 2004 2:50:09 PM (GMT Standard Time, UTC+00:00)
Hi Dare,

If you listen to the .NET Rocks episode with Clemens Vasters, he basically advocates the one parameter approach.

I buy it. With overloaded methods, you'll quickly run out of options to scale. And even if you don't, you'll end up with a bloated api. The importance of this is paramount when your clients are so loosely connected.

Just my $.02

-Brendan
Comments are closed.