box on soap

[Mark McEahern]

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnwsdl/html
/boxwsdl.asp?frame=true

Don Box on the Importance of Being WSDL
Don Box
Architect, Microsoft Corporation

February 2002

Summary: A personal appeal to the Web services community to make type-safety
a priority by writing WSDL for script-based Web services. (3 printed pages)

In watching the various Internet discussion forums, it has become glaringly
obvious that the development community at large is still struggling with how
the Web services fabric will be held together. By the end of 2001, everyone
in the emerging Web service industry had converged on SOAP. Based on the
raging debates held in 1999, this is amazing progress. Unfortunately, SOAP
alone is insufficient, just as XML before it was not enough. SOAP as it
stands today assumes that all parties "just know" what messages can be
exchanged and how they relate. Despite the persistent protests of one of the
original authors (yours truly), SOAP remains completely silent as to how one
becomes aware of this information. I personally believe that the relatively
late development of standardized discovery and metadata formats held SOAP
development back for most of 1999 and 2000.

Do what I mean, not what I say
Whenever two or more parties collaborate, some shared understanding of what
the collaboration will entail is needed. First and foremost, all parties
need to understand what it means to collaborate. What are the benefits for
each party? What are each party's responsibilities and obligations? This is
true in human interaction just as it is true in Web services interaction or
software integration in general.

The meaning and terms of a particular collaboration can be viewed as a
contract. In an ideal world, contracts would have crisp and concise
descriptions of the contract semantics and nothing else. For example, if I
hired you to mow my lawn, the contract might read as follows:

The reader will mow the writer's lawn once per week in exchange for ten
dollars.
This contract is pure semantics. You mow my lawn. I pay you. Clean. Simple.
Done.

Unfortunately, the US legal industry has made a fortune cleaning up the mess
made by contracts that look like this example. Why? Because the intention of
one or more parties is not adequately captured in the language of the
contract. The vagaries of the English language leave far too much room for
interpretation. For example, what if more than one reader were to mow my
lawn? Do I need to pay them all or just you (and you know who "you" are)?
Also, can I pay you in Canadian dollars? Can I pay you once per decade in
arrears? What recourse do I have if you do a bad job? In human contracts as
well as software contracts, the more intention that can be explicitly
stated, the less opportunity there is for misinterpretation.

In the world of Web services, there is a strong argument that contracts
should be stored and transmitted in a machine-readable format.
Machine-readable formats are preferable to non-machine-readable formats for
several reasons. For one, having the contract in machine-readable form
allows any number of features to be enabled, including validation,
acceleration, and deep tool integration. Additionally, once you have a
machine-readable format, you can write a program that transforms the
contract into any other known format. This includes transforming the
contract into human-readable documentation. The converse is not the case;
trying to harvest anything from normal documentation inevitably requires
lots of human intervention.

The idea of having machine-readable contracts is obvious to developers who
work in strongly typed programming languages such as Java, Delphi, or C++.
Unfortunately, the idea of machine-readable contracts is hard to swallow for
some programmers, especially those who have embraced the weakly typed world
of most scripting languages. However, until the entire world converts to
Perl, something needs to be done to enable strongly typed languages to deal
with Web services in a natural way.

A cry for help
I have tried over the years to convince the scripting community of the
merits of machine-readable contract formats. I have tried technical
arguments, but to no avail. I have been tempted to use ad hominem arguments,
but I can't bring myself to going that far. So today, I will try a different
approach based on personal confession and self-deprecation:



Hello, my name is Don.



I use strongly typed languages.



I need your help.



I have tried to use scripting languages exclusively. I really did.

I will admit that working in script made me feel free. It was exciting. It
was even addictive. Unfortunately, my addiction got the better of me.

My first problem was that sometimes my programs didn't always work. Try as I
might, sometimes I forgot to pass a parameter to a function. Other times, I
would pass parameters like "XXVII" or "Twenty Seven" to my math libraries.
My biggest problem was that my spelling is really horrible, and I found that
while many scripting languages are not case-sensitive, they all seem to be
spelling-sensitive.

What was really weird was that a lot of my programming errors never showed
up when I was testing my script programs. Instead, they always seemed to
surface after my users started to apply my programs out in the field. This
made me very unhappy, especially when it happened to users who had my home
phone number. I think my wife hated my use of script more than anyone. She
reminded me that we used to get a lot of the same sorts of calls back when I
worked in K&R C, and that once I switched to ANSI C, we got a lot more
sleep.

I found that by eschewing all alcohol and limiting myself to 30 minutes of
coding per day to reduce fatigue, I was able to get my error counts down
considerably. Unfortunately, I always find myself working with other
programmers, many of whom use strongly typed languages. I tried to get these
guys to use my programs with theirs, but it always led to problems. My
Windows-based scripts were accessible, but only through this thing called
IDispatch, which my C++ friends seemed to find offensive. They would often
write these weird-looking IDL files, often while saying some not so nice
things about me under their breath. I would try to convince them to move
over to script like me, but to no avail. I quickly found out that C++
programmers are the smartest programmers in the world, as each one I met
would quickly point out to me.

I must admit that I am weak. I ultimately succumbed to strongly typed
languages.

I was not strong enough to write code without the crutch of a compiler to
check my program for stupid errors and spelling mistakes.

I was not strong enough to ignore the taunts of my colleagues working in
C++.

And now, I need the help of the scripting community.

Despite the years I spent trying to make SOAP a standard way for programs to
communicate over the Internet; I find that raw SOAP and XML are at odds with
all of these compilers I am now using. I am told that if you give me
machine-readable contract definitions, my compiler can help me talk to your
Web services. A lot.

If you don't give me a machine-readable contract, then I am going to have to
write one of these weird-looking WSDL files by hand, and that always makes
me cranky. I understand that writing WSDL makes you cranky too, but I'll bet
if you wrote the WSDL once and put it on your Web site, everyone else would
just use it, and no one would ever need to write that WSDL again. And if you
wrote a ten-line WS-Inspection or DISCO file to go along with it, I could
find out about all of your other services too.

I know that WSDL isn't perfect. God knows I tried to make it better prior to
publication. Luckily, the W3C just launched a WSDL working group and it
looks like the community at large has the will to clean it up, just as SOAP
was cleaned up once it got the attention of a large community of
practitioners and experts. In fact, SOAPBuilders is running a WSDL bake-off
in February that surely will yield some progress on this front.

I also know that writing WSDL for your script-based Web services is more
work for you, but your suffering would benefit thousands or more developers
anxious to use your stuff. And just think of the nice things they will say
about you once you made their lives easier.

And not under their breath.

Related links:
WSDL 1.1 Specification
SOAP v1.1 Specification
Web Services Activity



Don Box is a leading educator, recognized authority on the Component Object
Model (COM), co-author of the Simple Object Access Protocol (SOAP)
specification, and coiner of the term "COM is Love." He recently joined
Microsoft as an architect in the Microsoft® .NET Developer and Platform
Evangelism Group. Box is the best-selling author of three books: Essential
COM, Effective COM and Essential XML. He is also writing a series of books
examining the .NET strategy entitled Essential .NET. Earlier in his career,
Box co-founded DevelopMentor Inc., a component software think tank aimed at
educating developers on the use of the COM, Java and XML. A popular public
speaker, Box is known for engaging audiences around the world, combining
deep technical insight with often outrageous stunts—not the least of which
was conducting a discussion on SOAP while in a bathtub full of suds at
Tech·Ed 2001 in Barcelona. During his free time, Box enjoys jamming with
fellow MSDN Magazine contributors in Band on the Runtime, which performs
songs on various programming topics. Box is also responsible for the
creation of a fashion line, starting with Don Boxers.