Overview of Contract-First Web Service Development

If you are new to the concept of contract-first web service design, I’ve got a couple of pointers for you.

Messages, not Methods

As Aaron Skonnard puts it:

A service is a piece of code you interact with through messages. Services are passive. They wait for incoming messages before doing any work. Clients are the initiators. Clients send messages to services to request work.

Contract-first advocates planning what messages a web service and a client would exchange as the first step in development. 

Yasser Shohoud wrote a great article back in 2002 entitled Place XML Message Design Ahead of Schema Planning to Improve Web Service Interoperability (read article). A couple of interesting points:

• You should know what kind of data will be returned by Web Service requests and use the structure of that data to design the most efficient message format.
• Web Services are all about supplying the right data at the right time. When a client calls a Web Service, an XML data message is sent over the wire and a response is returned to the client. 
• When you program the Web Service and its clients, you are really programming against these messages. The data in these messages is ultimately what the application cares about. So why would you create a Web Service beginning with the classes and methods and let the tools create the message schemas for you? You should design the data (message) schema and implement the Web Service to fit this design, like you would when designing a database schema.

This goes against the “common” approach of writing code, then slapping the [WebMethod] attribute on methods and shuttling DataSests across the wire. What this does is fakes the old RPC.

For more contract-first goodies, check out Contract-First Service Development and Techniques for Contract-First Development by Aaron Skonnard.

I'm not completely sure I'd agree with this, although I haven't given this a whole lot of thought yet. I always think about a Web service or just a facade layer in general as being a simplified interface into an *existing* domain. Sure you could design the XML schema of your service first, but, as you say, this is akin to designing your database schema up front (which is really bad if you're an XP'er, and really good to some others).

Btw... In some circles, 'methods' are called 'messages', the difference in this case is just the interface (a webservice method takes a string of text, when you get right down to it, and a regular method takes some other object like a DTO). If you design your web service interface *after* your domain, all you have to do is translate that string of XML text into an object suitable for your domain, and then delegate to an existing method.