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:

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.