More on Contract-First Web Service Design

April 26, 2005

@ 02:52 PM

Aaron Skopnnard has posted a response to my Contract-First XML Web Service Design is No Panacea blog post. In his post The virtue of contract-first Aaron Skonnard writes

I love being challenged on my opinions. I've been challenged extensively regarding my opinion on contract-first development, although mostly by folks at Microsoft like Don , Doug , and Dare . The funny thing is when I have the same discussions with folks in the field building systems today, it's a no-brainer.

So why the disconnect between vendors and the rest of the world?

I believe it's because most vendors don't see (or appreciate) the main virtue of the contract-first approach, which has more to do with collaboration than interoperability. The latter is a result of the former. Let me explain.

Interoperability is the net result of a well-designed contract. By "well-designed" I mean a contract that experiences fewer interoperability issues when used across a variety of toolkits. Simply using contract-first does not guarantee a good contract. However, increased collaboration during contract does. This means getting all parties (everyone who will have to deal with the contract) involved early, during design, so you can identify what will and won't work in each implementation environment. This allows you to bring local expertise to the table early in the process before the implementation investment begins. This process influences the subset of XSD constructs that can be safely used given the identified limitations.

The first thing that I'll point out is that I'm not a 'vendor'. Now that I work at MSN, I am as much a customer of the XML Web Services stuff coming out of the Indigo folks as anybody else. My approach to XML Web Service design comes from the perspective of having to figure out what strategy we should use when deploying services that will be used by millions of customers either directly or indirectly.

With that out of the way, I can focus on the fundamental error in the generalization presented by Aaron Skonnard. He writes "This means getting all parties (everyone who will have to deal with the contract) involved early, during design". Unfortunately there is simply no chance that

providers of XML Web Services on the Web whether they are big companies like Microsoft, Google and Amazon or small startups like del.icio.us, Bloglines or Flickr can poll all the potential users of their XML web services to figure out what XSD constructs their toolkits can handle and then design a schema that uses the intersection of these features.

The approach Aaron encourages may work if you are in a small company and are designing services that will be used by a few parties but doesn't really work if you are providing services on the Web or even at a large company where it is hard to get everyone who will be using the service in the same country let alone the same meeting room. The latter scenario is what likely happened in the original mail to XML-DEV which sparked my blog post on Friday.

I should clarify that when I say 'code-first' development that this doesn't mean that there shouldn't be guidelines as to what types are exposed as XML Web Services. At work we've settled on using a small set of types within XML Web Services; System.Int32 and other numeric types, System.Double, System.String, System.DateTime, System.Boolean, various instances of System.Enum and arrays of System.Byte for base 64 encoded binary data. The only collection types we pass around are arrays. This maps to a very small subset of XSD and is reminiscent of the set of types supported in XML-RPC.

With these guidelines our developers can build XML Web Service applications in a 'code first' manner yet have a high degree of confidence that the services we build will be interoperable across various toolkits. One doesn't have to be an expert (or even deeply knowledgeable) about complex technologies like XSD and WSDL to build XML Web Service applications in this manner. And quite frankly, I think it is a waste of our developer's time to make them experts at these technologies when it tangential to the bulk of the work their code has to do.

Categories: XML Web Services

« Fun with XMLHttpRequest and RSS: Browsin... | Home | Please Review: Table of Contents for v2.... »

Tuesday, 26 April 2005 16:00:08 (GMT Daylight Time, UTC+01:00)

I think I heard an Amazon person quoted as saying "XML-RPC offers 80% of SOAP's capabilities for 20% of the complexity." That's accurate in my experience, but I haven't been happy with the results I got from either of them.

I gotta say, I'm totally mystified by the dichotomy of XSD kitchen sink vs. object mappings. Whenever you mention mappings to C# types, it sets off this thing in my head wondering why that would be desirable. Is the goal to shield your devs from the XML parser and the HTTP library?

Robert Sayre

Tuesday, 26 April 2005 16:06:59 (GMT Daylight Time, UTC+01:00)

> Whenever you mention mappings to C# types, it sets off this thing in my head wondering why that would be desirable. Is the goal to shield your devs from the XML parser and the HTTP library?

The goal is to shield my devs, testers AND myself from the complexity of WSDL and XSD not XML and HTTP.

Dare Obasanjo

Tuesday, 26 April 2005 16:15:08 (GMT Daylight Time, UTC+01:00)

Dare - it seems you must have missed the following paragraph in my post:

"Obviously there are situations where you cannot collaborate with all your consumers ahead of time, but in many of the common enterprise integration scenarios you can. When you can't, one should definitely stick to a subset of XSD that will be most likely to work with as many possible consumers. These subsets, however, are just the documented best practices that came from the type of collaboration I described above."

That doesn't sound like the "fundamental error in the generalization" you attribute to me.

Aaron Skonnard

Tuesday, 26 April 2005 17:14:10 (GMT Daylight Time, UTC+01:00)

"The goal is to shield my devs, testers AND myself from the complexity of WSDL and XSD."

There's the problem right there. Why patch around stuff that is plainly not delivering? What's worse is that this was predicted to happen, no matter how much soapbuilding and tool development was undertaken. I don't know whether to be delighted with this sequence of entries of yours, or be insanely annoyed it's going to take until 2006 for this to get into mainstream thinking.

I don't see how object first is going to be any better than contract-first. Half the WS technology that exists was invented to pach around variance in object models. CORBA, bless it, ended up with SOAP/WSDL/XSD as a simplification. Round and round.

Otherwise what you're advocating is the 'known-subsets' approach (aka de-facto standards). Which will work, at least in terms of eking out what the real standards are. but honestly, forget about Objects and about forget about Contracts if 'Object' means 'whatever's in the CLS' and 'Contract' means 'whatever my tool's definition of XSD+WSDL is'. Keep data types optional, and stick to XML structures that map easily onto dictionaries and lists, which are easy to consume.

Bill de hOra

Tuesday, 26 April 2005 18:29:08 (GMT Daylight Time, UTC+01:00)

When I said "your devs", I meant the target developers of any MSN API. Is that what you meant?

Robert Sayre

Tuesday, 26 April 2005 18:54:51 (GMT Daylight Time, UTC+01:00)

Aaron,
I don't think the same decisions you make when determining what subset of XSD to use in an Enterprise where a handful of different toolkits will be used are the same when putting a service on the Web where people could be using Java, Perl, Python, .NET or what have you.

Robert,
My answer is the same. The goal is shielding people from the complexity of WSDL and XSD not HTTP and XML.

kpako@yahoo.com (Dare Obasanjo)

Wednesday, 27 April 2005 08:35:36 (GMT Daylight Time, UTC+01:00)

I'm with Aaron on this one. I think Dare and Don's comments show very little understanding of how enterprises manage their software development. Architects are interested in designing the interfaces between systems. Tell them to go write objects first and they will laugh you out of the building. They want to leave the detail of the internal implementation to Dev leads/Designers, but do want to make sure the interface is 'right'. They have the knowledge and expertise to know what makes a good and bad interface, but want the tools to enable them to do that. Right now I see people hand-crafting this, or using something like XML Spy. What we at Microsoft need to create is a first class contract design tool built into Visual Studio Architect Edition. I was hoping the Indigo release would add something like this, but if Don's comments are anything to go by, we will be dissapointed :(

Mark Bower

Wednesday, 27 April 2005 10:42:58 (GMT Daylight Time, UTC+01:00)

Mark,
(a) My scenarios for XML Web Services do not involve some architect designing APIs between internal systems but instead websites putting services on the Web for all and sundry to access.

(b) There seem to be lots of design tools for doing high level design of classes as far as I can tell. Exactly why can't these "architects" use these design tools when building their interfaces between systems?

Dare Obasanjo

Wednesday, 03 August 2005 20:41:55 (GMT Daylight Time, UTC+01:00)

Which approach should one favour when designing common set of domain data types to be used across multiple services in the Enterprise? It would be preferable to scope simple common types in a dedicated namespace, the same may be true for higher-level data types. This would provide a set of reusable message building blocks for future development.

This is desirable because a client may need to communicate and pass data between several services. Considering strongly typed nature of modern languages it would be preferable to have consistent type packaging across services. This would also promote reusable message processing code.

I can see this task easier accomplished by defining Schemas first, publishing and reusing them across the Enterprise. This could also be accomplished by writing and distributing common code first. Would it be easier?

Oleg Proudnikov

Wednesday, 03 August 2005 21:27:04 (GMT Daylight Time, UTC+01:00)

Which approach supports designing extensible schemas - schemas that can support compatible evolution of messages?

By dersigning the schema first one could use techniques described by David Orchard (wrapped wildcards) and Dare himself(sentries) that make older schemas validate newer messages and newer schemas - older messages.

Can the same be accomplished with code first?

Oleg Proudnikov

Comments are closed.

Dare Obasanjo's weblog

"You can buy cars but you can't buy respect in the hood" - Curtis Jackson

Navigation for More on Contract-First Web Service Design - Dare Obasanjo's weblog