WSDL - Why Services Don't Launch

Last week was enlightening. I'm working on a project that is providing a set of services for internal consumption. The interface is actually pretty simple. We have four entities, CRUD on 3 of the entities and two operations on the fourth. Conceptually the interface can be described in five minutes. It can be expressed rigorously in any OOP language in about an hour. (The service implementation is considerably more complex, but the interface is relatively straightforward).

We opted to implement the services using SOAP. Enter WSDL. The conceptual interface was translated into WSDL which took more than a day. Once the WSDL was finally validating, we were able to generate code in Axis. Then we moved on to C# and GSOAP. Neither of them would work without further modifications to the WSDL. Another day lost on compatibility. Once the servers were deployed, we ran into issues where GSOAP generated code that compiled but didn't work. There were name space challenges. What took the engineers an hour to express in Java was taking days to express in WSDL. And I want to reiterate that this is a relatively simple interface.

Why didn't we just write the interface in Java and use java2wsdl to generate the WSDL then? Well, one reason is that the services have to be split for security reasons which leads to different ports in WSDL terms. Auto-generated WSDL would not have captured the common types with the appropriate file structures. And philosophically, if WSDL is my implementation neutral interface definition language, then it seems I should be writing it, not generating it from a specific implementation of the interface. Finally, from a stylistic point of view, I'm still waiting on the code generation process that makes files that are easy to read and understand by humans.

As long as we're on the subject of human readability, WSDL fails miserably at this quality. It is similar to reading XML schemas, only harder. Some of you may decide at this point that I'm not much of a software engineer if I find XSD and WSDL difficult to read, and so be it. But I can read a DTD and RELAX NG specifications with ease. I would expect any specification that purports to be a mechanism to allow developers to communicate interface semantics to be clearly understood by developers and not force them to rely upon tools to translate into languages they know.

"So what", some will argue. WSDL is about allowing tools to generate interfaces and is not intended for human consumption anyway. I'll argue that it lacks sufficient constraints to allow that to work well either. What does a java.util.Date map into in C++? What does an unsigned long long map into in Java? The entire XSD type space is available in WSDL which leaves the door open for developers to create unusable interfaces, especially if these interfaces were code generated from an implementation interface.

Yes, I am a heretic. I dare to boldly state that WSDL is an impediment to building services. I'm sure the intentions were good and honorable but the result misses the mark. There is a next generation WSDL in the works but it doesn't appear the primary goal is to improve either of these issues. If anything, I am concerned that 2.0 will get further from human readability than 1.1.

What is the answer? I don't think the answer is to abandon the concept of specifying interfaces. Quite the contrary, I am a big fan of having a way to express the semantics of interfaces in a way that is better defined than natural languages. The specification should support more than just SOAP interactions though. Ideally, I would like an IDL that could accomplish the following goals.

• Provide syntax and semantics that are more readily understood by developers. I think XML is a reasonable tool for such an IDL but the focus should be on readability. Think RELAX NG vs XSD and you have the idea.
• Support a variety of interactions. SOAP has WSDL although there is no reason a new IDL couldn't easily express SOAP interactions. It should also be possible to describe REST interactions with this IDL.
• Provide more control over the transport binding. The primary transport in use today is HTTP. My IDL would allow me to leverage all HTTP operations, specify headers that are meaningful as well as the content-type of the body. This would allow operations that supported any of the available media types to be expressed. Other transports could be supported but in each case, the binding semantics need to leverage the full richness of the transport.
• Don't preclude code generation. There is nothing wrong with code generation, I just feel that it should go from the IDL to the implementation and not vice versa. Partial code generation should also be supported, say for example just type handling.

I have spent the past few weeks thinking about how such an IDL might look. I've also struggled with questions of usefulness and adoption. I'm certain that having nothing is the wrong answer and my experience to date with WSDL tells me it is a suboptimal solution.

What do you think? Leave your comments or trackbacks and let me know.

Technorati Tags: architecture, engineering, http, java, programming, wsdl, rest, scalability, services, soa, software, to_read, toread, web

Comments

[Mark Baker]

"My IDL would allow me to leverage all HTTP operations"

Does ... not ... compute. Can you explain what you mean?

[Dan Pritchett]

All I was trying to say is that a service "invocation" should support binding to GET, POST, PUT, or DELETE. WSDL limits you to POST which as you well know means you can't express something as simple as an RSS feed. My goal would be that, while arguably unnecessary, the IDL could easily describe an RSS feed or WebDAV.

[Bill de hOra]

"I have spent the past few weeks thinking about how such an IDL might look"

The state of the art for interface semantics beyond natural language is RFC2119. And mustIgnore. I'm not joking.

No argument from me re the WSDL. Don't deploy on it unless you have to for partnering reasons.

[Libor SOUCEK]

Maybe SSDL can be your alternative language (http://www.ssdl.org/)?

[quark]

Having an easy-to-read-and-write-by-humans IDL that is similar to RelaxNG is more than welcome!

Using RelaxNG's Compact syntax and RelaxNG itself as the schema language, as well as being able to express bindings for HTTP (including all its methods and headers) and other protocols would be totally awesome. You'd have me onboard as a vivid fan at least!

[John "Z-Bo" Zabroski]

Sounds like WHISKY syndrome: "Why isn't someone koding yet?"

I'm just a college student, so tell me, what happens when your team of engineers change the model as they code? Once you are done with specification (the WSDL), is all of this roundtrip engineering being updated throughout the design and testing of your conceptual construct?

[sergei anikin]

Dan, I think, there are two problems, you exposed in your post:
a) Implementations incompatibility, we really can't do much about it.
b) Luck of proper language editor, here I can propose you to look at MPS, product being in the concept phase by our beloved Idea IntelliJ developers(JetBrains). Their idea is, that it is not enough to have language defined and translation implemented, you need a reasonably good editor to be effective in the language usage. This was the case for Java, before IntelliJ arrived, it is the case you are discussing in this article.

[Jacek]

Dear driveawedge (can't find your name), I agree with you that WSDL is hard to author and that tools are often bad. But some of your issues seam mislead:

The IDL should be a common langauge, and as such it does not have to talk about java.util.Map or unsigned long long. Instead, WSDL chooses XML (and I haven't seen you complain about it) and XML Schema (but WSDL can easily cope with RelaxNG, too). IIRC, RelaxNG also uses XML Schema datatypes because they seem to be a good set of data types for XML data. Mapping of that into languages, if desired, is out of scope for this W3C effort.

You may want to have a look at W3C XML Schema patters for data binding at http://www.w3.org/2002/ws/databinding/ - they are trying to document commonly supported patterns in XML Schema, and they you may restrict yourself to that for interoperability.

WSDL 2 also aims to give you good support for binding to HTTP operations.

Perhaps all that's missing in WSDL is just the human-readable syntax, a la RelaxNG compact? Care to propose it?

BTW, make the comment window bigger, please.

[Dan Pritchett]

You missed my point on type bindings. I understand that WSDL is language neutral and relies on XML bindings. My point is that if you suggest developers express interfaces in a native language, you expose them to the possibilities of picking types that are not terribly neutral. Thus the argument for having an IDL that is understandable by people.

[David Chazin]

Yes, WSDL is hard to read. It need to be approached like a foreign language, which means it will take time. Even worse is that most of the tooling stinks so you are almost forced to have to hand tamp it to get it to work properly if you are dealing with multiple target environments and languages. Also errors are really hard to track down. Part of the problem is that multiple xml namespaces have to be used everywhere, which makes the xml part of the processing much more complicated and harder to understand.
Another issue is expectations. I expected that using wsdl should be easy. Actually it is quite difficult and nuanced to understand and use and has a very steep learning curve.
The good news is that once you "get it" you can read it and crank out services as fast you think you should have been able to when you first started.

[Leshek]

Maybe WADL will do better :-)
http://en.wikipedia.org/wiki/Web_Application_Description_Language