« Dependency Injection - Good or Bad Practice? | Main | Know your LINQ »


Contract-first vs. Code-first Web Services Development

Dare Obasanjo is commenting on an InfoQ article entitled “Code First” Web Services Reconsidered. He states that the question shouldn’t be about whether you should prefer contract-first or code-first:

The only real consideration when deciding between “code first” and “contract first” approaches is whether your service is concerned primarily with objects or whether it is concerned primarily with XML documents [preferrably with a predefined schema]. If you are just moving around data objects (i.e. your data model isn’t much more complex than JSON) then you are better off using a “code first” approach especially since most SOAP toolkits can handle the basic constructs that would result from generating WSDLs from such types. On the other hand, if you are transmitting documents that have a predefined schema (e.g. XBRL or OOXML documents) then you are better off authoring the WSDL by hand than trying to jump through hoops to get the XML<->object mapping technology in your off-the-shelf SOAP toolkit to do a great job with these schemas.

According to Dare the main problem lies in the impedance mismatch between W3C XML Schema (XSD) and objects from your typical OO system. Every SOAP Web Service publishes a service contract, which described the document types based on XML Schema. The problem with XML Schema is that it offers a much more complex type system than any known OO language. Thus interoperability issues cannot be avoided when putting XML (De)Serialization to use, because simple types might be mapped correctly, but complex types often pose problems for the serialization engine.

Dare suggests to revert to RESTful Web Services, which omit the problem by simply doing without XML Schema based contracts:

One of the interesting consequences of the adoption of RESTful Web services is that these interoperability issues have been avoided because most people who provide these services do not provide schemas in the W3C XML Schema. […] That way XML geeks like me get to party on the raw XML which is in a simple and straightforward format while the folks who are scared of XML can party on objects using their favorite programming language and platform. The best of both worlds.

Although I have once rightly been put on the SOAP side of the Tilkov Scale, I’m starting to switch sides - for better or for worse …

Posted by Hartmut Wilms at 29.08.07 11:13


It’s not a matter of avoiding schemas, it’s a matter of understanding their function and meaning.

Runtime schema validation is an antipattern because it is crushingly expensive and adds no value. What a message producer (unless it is defective) puts on the wire IS the message; and message consumers always have the option of either tightening or lossening the type for their own purposes.

There is still value in defining the type abstractly and with the greatest possible degree of rigor. That is the minimum role of a schema even if it plays no role at runtime.

Posted by: Frank Wilhoit at 04.09.07 14:31

Sorry for answering that late. I’m drowning in junk comments and therefore it’s not that easy to pick out the valuable ones and publish them.

The (only) thing that I really like about XML Schema is the one you call an antipattern. In my opinion the complex type system (including all constraints) of XSD is worth the pain because you can use XSD to define the structure of your documents at design-time AND check incoming documents at run-time. Design and validation are both based on the same system regardless of the platform you’re services are build on. That’s a great gain!

Think of checking a zip code. The rules for valid zip codes are defined in your published interface and at the same time checked according to the same interface definition.

Posted by: Hartmut Wilms at 10.09.07 15:59