Contract First web service design
The debate about the “contract first” approach to designing web services has been raging again. This usually revolves around whether to design WSDL and XSD first and then implement this, or whether to write the code first using your favourite WS stack and use the WSDL that results.
First, here are some of the recent posts discussing this issue:
- Aaron Skonnard’s Contract-First Service Development article in MSDN magazine.
- Dare Obasanjo: Contract-First XML Web Service Design is No Panacea
- Aaron Skonnard: The virtue of contract-first
- Dare Obasanjo: More on Contract-First Web Service Design
- Simon Fell: Dare on contract first
- Tim Ewald: Dare argues that code-first is better for interop
- Craig Andera: Contract First? Code First? Both First.
- Aaron Skonnard: How do you stop the leak?
This is an interesting discussion and clearly one that isn’t new. Some of the comments to these articles provide diverse views also. Fundamentally, though I think some of the contributors are deliberately finding fault with a strict definition of code-first or contract-first to promote their view.
I get to work with a wide array of developers and architects. Mostly, I see people who are comfortable in the code world and less so in the XSD/WSDL domain. The model I have adopted and have been promoting for the last couple of years is one of code driven contract development. What I mean by that is to focus on the contracts that your services will expose first, but define them using code to represent the service end-points and the messages that will be passed.
Look, many of the people I interact with have the following properties:
- they are very comfortable with writing code
- they are comfortable with XML
- they understand XSD but reading is easier than writing
- they don’t know much about WSDL
Given this, it makes sense to develop interfaces written in code but keep the XML in mind and adopt some pragmatic guidelines about the shapes of data that interop well as Dare recommends. Simon argues that this means some people who know XSD/WSDL must be involved in a way that suggests he thinks this negates the argument. The truth is that, yes, this is necessary, but it doesn’t require a large part of the development team to know about why the guidelines are the way they are as long as they stick to them.
In Aaron’s MSDN article, he contrasts VB6 and IDL development against “code-first” vs. “contract-first” web development, but to be honest I don’t think it is a completely valid comparison. Considering the IDL is very similar to C/C++, writing COM components using IDL with an implementation in C++ isn’t that dissimilar to the approach I propose for web services. Yes, separate interface from implementation but don’t force people to use completely different syntax.
So my view is close to Craig’s in that it’s less about what you call yourself and more about your approach. I think it might be unrealistic to expect a whole development team to understand the stack end-to-end and that shouldn’t preclude them from being involved in the design process. Today, though, if interop is your goal then you do need to have people that understand what’s going on under the covers, as Aaron says, for when those abstractions leak.