RE: One parameter to rule them all: Part 2
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", "98052"):
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.