Web Service Design: Contract-First or Contract-Last?

Web service design seems to come in two flavours contract-first and contract-last. Contract-first starts with designing the XML schema / WSDL and then creating the Java interface based upon the schema.

Contract-last takes an existing Java interface and from that, creates your web service. On reflection, you’d think that this meant create a schema contract, but generally it seems to mean getting hold of some tool that will take a Java interface as an input and deliver a WSDL as an output.

Research seems to show that, at the time of writing, contract-first is preferred over contract-last and various reasons are given:

• Object to XML impedance mismatch, which generally means that with contract-last, some Java types don’t readily convert to XML and if they did then there could be a certain loss of information as defined by an XSD’s <restriction> element. I.e, Java isn’t really expressive enough to produce a rugged contract.
• Contract-last could suffer from performance issues as you, the developer, have no control of what’s sent over the wire.
• Using contract-first means that you have your XML types defined in a set of separate schema files, which could be re-used effectively.
• Contract-first has looser coupling between definition and implementation making version management easier.
• One of the positive things about web services is that they allow services written in different languages to work together. Contract-first reinforces this approach as the WDSL / XML Schema provides a programming language independent, centralised method of specifying a contract. Contract-last, on the other hand, means that your contract is defined in your implementation code, which may differ from your client’s implementation code and who’s to say which is the master copy of the code?
• Which brings us on the next benefit of using contract-first: the management of change. There is usually a version 2 of an interface adding in something that was forgotten in version 1. Using a schema makes that change management easier.
• Finally, a plus point for contract-last is that it should be easier, there’s no messing about with XSDs, meaning there are no extra skills for your team to learn.

This is not a complete list, but should underline the reasons why contract first seems to be the preferred choice. Additional reading can be found in the SOA World Magazine

The guys at Springsource take a slightly different approach: they seem to prefer contract-first but WDSL last, and by that I mean that you specify your schema, but they use it together with some other config details to generate your WSDL, but more on that later...