Leo's Technical Blog

Don't start explaining the effects of your design decision. Causes come first.



Leo Soto

advising, .net, xml

Don't start explaining the effects of your design decision. Causes come first.

Posted by Leo Soto on .

advising, .net, xml

Don't start explaining the effects of your design decision. Causes come first.

Posted by Leo Soto on .

A few weeks ago, I had an interesting meeting with the system architect of one of our customers (and a few other people from both sides). We are doing a new version of the transactional web site for their customers, and in the project there is a (IMHO) good separation of concerns: They build the infrastructure (which only they know), we build the web front-end (which is our main expertise). And webservices were set as the way to go, they serving, we consuming.

The issue was that every webservice returned a string. And such string always contained an XML document! Wait, I said to myself (well, and a bit louder so my coworkers could comment on that): Why in the hell are they wrapping XML documents inside an XML-based protocol which anyway will transport everything as XML, but, according to a schema will in fact represent some sane data structures, and, when using the adequate tools, I (almost) shouldn't care that the XML serializing is happening? They throw away all the benefit of using webservices when decided to use them to transport strings containing XML, which I should deserialize on my side! I was tempted to write my first entry on the Daily WTF.

So we set the meeting and it started something like:

  • We have no problem using WS, but could you guys please return some actual structures instead of strings?

  • Well, no. We are standardized in this way.

  • But you are giving us a unnecessary pain forcing us to decode every XML returned by your services.

  • But there are advantages too: We can add information to the returned structures without bothering our clients, ....

Something like ten minutes passed arguing about the benefits and disadvantages of their strategy, until somewhat our previous point ("You are forcing us to do unnecessary things") was raised again, and then they responded:

  • Hey, you don't have to do that! Just use XSLT, XPath, etc to get the returned data into the users screen.

  • Well, but what if we don't want to use all that XML technologies?

  • Uh, why would you do that?

  • We aren't comfortable with them. But anyway, somewhere in the process you are hand-serializing your data as XML, to return that to your clients. We just ask you to don't do it and just returning the actual data, relyin on WS to do the serializing and deserializing work.

  • Er, we don't serialize the data to XML by hand on our webservices. Our webservices get XML from another layer, which in turn also receives XML from
    the database!

  • Oh. I So you don't deserialize on the webservice and instead just serve XML to your clients because some of them doesn't care and just use XSLT, XPath, etc to process it.

  • Right. And that's the great majority of our clients.

Bingo. They reason behind returning strings were not the benefits argued in the middle of the discussion (in which both parts agreed almost nothing). They did that because it was the most reasonable decision given the circumstances. And now that I know that, I also know why they will not do what we wanted: It's too expensive for them. They would have to do exactly what we don't want to, instead of do less work as we expected.

I could not agree with every detail of their solution (they could serve the XML simply over HTTP, instead of XML over SOAP over HTTP), but they aren't big or really important points. But I only could came to this conclusion when I learned the causes of their choice. If they had started explaining that, instead of selling us the side effects, this meeting would have lasted much less, or even would have been unnecessary.

Note that I also made the same mistake. When asked why we wouldn't use XSLT to process their output I said that we didn't liked it, or something along the lines. I should have been clear and said that our web designers weren't capable of working with XSLT, and were much more comfortable doing simple templating using something like ${user.name}. It's true that I'm not a big fan of every XML technology, but that wasn't the main reason. It's only that it's much more fun to argue about the pros and cons of the consequences of some design decision that we tend to forget the root causes.

Just for the record, I decided to ask for the XML schemas and documentation for every "XML service". Dot NET serialization framework should do the boring work, and keep everyone happy.