Primary Menu

A Case for WSDL – Why REST is not the only answer

I have been reading a lot lately about people hating on SOAP based web services. As a whole, the Web is moving more toward REST based APIs. This post is to make a case for WSDL and SOAP based web services.

Don’t get me wrong. I’m a huge fan of RESTful Web Services. I use them in many places where they make sense in the software I develop. I am not writing this post to say that SOAP/WSDL based web services are better than the REST style but I intend to point out some of the things that a WSDL does better.

It all comes down to perspective. Who is going to be consuming the Web Service? Is the consumer going to be a human or a machine? Let’s look at each case.

Humans Consuming Web Services. By humans consuming web services, I mean a programmer sits down and writes some code to use a web services. The common example of this is a developer from a website using the Flicker, Twitter, Google Maps or Facebook API to integrate with their site. Even in the business world, when a user needs to write a piece of code to connect two things together, REST is the clear winner. REST style web services are easier to work with and usually result in much cleaner code.

Machines Consuming Web Services. By machines consuming web services, I’m referring to software that interprets and leverages the web services. The primary examples for this are Business Process Management and Runbook Automation Software. This happens to be the area in which I develop software. In this space the goal is to allow machines to interpret the Web Services (or other technologies) and allow the user to just map from service to service. The user needs to know nothing about the transport or how the service function themselves as the machine is responsible for all of that. This type of software is typically used in the business world and not on the Web.

For this type of software, a strictly defined specification (a WSDL) provides a valuable tool to the software that needs to interpret it. A REST web service may be easier for a human to use by reading documentation, but we have yet to make a computer read documentation and produce results. Also, many REST style web services have XML formats that cannot be expressed in a Schema. This may be fine for a human, but XML Schemas provide an easy way for a computer to consume and understand the XML format. Yes, XML Schemas are very wordy and difficult to read by a human. They are also a pain to write properly. Even with their limitations, they do a good job of defining XML in a way that a machine can interpret them.

I see a lot of newer programmers who have only ever done work on the Web claim that REST is the best choice in all cases. We have graduated beyond SOAP to the superior technology. Even Joel Spolsky mentioned it on episode 64 of stackoverfow. REST as a superior technology is simply not true. REST may be the best choice for the Web but there are many other uses for Web Services besides the Web.

REST is getting closer to what WSDL has to offer. With WSDL version 2.0 or WADL you can define REST style web services. Maybe in a few years things will be different. Maybe we will get to the point where REST really is better than traditional web services. But we are not there yet.

3 thoughts on “A Case for WSDL – Why REST is not the only answer”

You’re quite right that a lot of developers recite other peoples opinions of REST vs SOAP without having any personal experience to back up their uninformed choices.

Its also interesting that you said WSDL and not SOAP as a whole… because I think the sweet spot lies in REST which properly strict APIs ala WSDL.

I’ve been writing a lot of client/server applications in the last 3 years and ofcourse I have always used RESTfull interfaces b/w the two where I had control them, but recently (about 6 months) I’ve had to deal with ASN.1, SOAP, WSDL, CORBA and finally understood what I had been looking for while doing my REST services. I had been looking for an IDL to basically automate my creation of client code. While REST servers are easy to author, there’s no easy cut dried and pasted way of creating clients that implement the server protocols.

I want to believe any decent developer will reach the same conclusions after developing a little bit too much REST clients against services. Too much typing man.. too much brain dead http calls, json.dumps(), etc

To quickly end this rant ;), I’ll summarize by saying… We tend to throw away the good lessons from the past for the next sparkly new invention/innovation, instead of building on them… ASN.1 was developed a while back and IDL is generally agreed to be advantageous when designing protocols/services. Thought SOAP may be generally bloated and thought REST may be lighter weight and generally easier to develop against, REST still needs something akin to WSDL… an IDL that allows RESTfull services to be easily spec’d and allow clients to automagically generate code for talking to them.

Oh… and a closer look at Thrift and Protocol Buffers also shows that this is a problem worth solving.

I think that SOAP and REST both provide advantages depending on the problem and environment. However, I would like to make a few arguments in favor of why REST has some key features that actually make it more friendly in the area of Machines Consuming Web Services.

– Uniform interface —
If a human or a machine looks at the WSDL interface, how do they tell which methods create the resource, update or delete the resource? You would have to get everyone to use the same naming conventions in order for it to be clear without consulting external documentation, which a machine can’t do and won’t easily be able to understand. With REST it’s very clear what standard HTTP methods you can use in the most common CRUD operations.

– Hyperlinks in resources —
A well-designed REST API uses hyperlinks in the resources, so you know what else you can do with the resource. This is the HATEOAS feature and is the most often looked aspect of REST. It allows a machine to discover what states are possible for a resource and what are the related resources. That feature built on the uniform interface, in my opinion, actually makes it easier for a machine to determine what it can do when
in encounters a completely new web service. And with the support of AtomPub
some of these states are more explicit for a machine to understand. With WSDL it’s easier for the machine to parse, but a human user still has to map those operations to their actual meanings before anything useful can be done.

– Known side-effects —
The caller clearly knows side-effects and which calls are idempotent. Whether a SOAP method call is going to have side-effects is not known. With REST it’s known implicitly by the HTTP method being used by the caller. WSDL does not encode what web methods have side effects.

– Standard error codes
With REST you have a standard set of HTTP error codes. Sure you have the SOAP fault, but my understanding is the interpretation of that fault is mostly application dependent. There is no standard way of encoding specific failures related to the operation that a machine can understand. On the other hand, with REST combined with known side-effects, a caller can make a more well-informed choice about the repercussions of re-trying a REST call.

You’re quite right that a lot of developers recite other peoples opinions of REST vs SOAP without having any personal experience to back up their uninformed choices.

Its also interesting that you said WSDL and not SOAP as a whole… because I think the sweet spot lies in REST which properly strict APIs ala WSDL.

I’ve been writing a lot of client/server applications in the last 3 years and ofcourse I have always used RESTfull interfaces b/w the two where I had control them, but recently (about 6 months) I’ve had to deal with ASN.1, SOAP, WSDL, CORBA and finally understood what I had been looking for while doing my REST services. I had been looking for an IDL to basically automate my creation of client code. While REST servers are easy to author, there’s no easy cut dried and pasted way of creating clients that implement the server protocols.

I want to believe any decent developer will reach the same conclusions after developing a little bit too much REST clients against services. Too much typing man.. too much brain dead http calls, json.dumps(), etc

To quickly end this rant ;), I’ll summarize by saying… We tend to throw away the good lessons from the past for the next sparkly new invention/innovation, instead of building on them… ASN.1 was developed a while back and IDL is generally agreed to be advantageous when designing protocols/services. Thought SOAP may be generally bloated and thought REST may be lighter weight and generally easier to develop against, REST still needs something akin to WSDL… an IDL that allows RESTfull services to be easily spec’d and allow clients to automagically generate code for talking to them.

Oh… and a closer look at Thrift and Protocol Buffers also shows that this is a problem worth solving.