Partager via

RE: One parameter to rule them all: Part 2

  • Article

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.

Comments

  • Anonymous
    November 29, 2004
    I might be wrong, but ASMX does not allow overloads, do they?

    If this is true, this would be a compelling argument for the "uber-parameter".
  • Anonymous
    November 30, 2004
    However, the first example would be more like a RPC call which is also something to be avoided. It has been preached that each request should be treated as a message or document and not like an RPC call.
  • Anonymous
    December 03, 2004
    I don't think RPC calls are all bad - in many situations you need to go the RPC route (for example a temperture web site - you can't tell the user - Ok we have submited your request - please log back on in about 2 minutes and we should have the answer for you then) rather the procedue call is an integral part of the process - if the procedure dosn't go thru then we have to stop the process.
  • Anonymous
    June 13, 2009
    PingBack from http://outdoordecoration.info/story.php?id=2015