Wednesday, September 23, 2009

WSDL 2.0 - a REST Friendly Language

Originally posted 07/20/07 @ 12:47:55 pm

W3C has published the Web Services Description Language (WSDL) Version 2.0 Recommendation. That means we can talk about a new standard now.

From history, you can recall SOAP was not a standard by committee but a de facto one, and WSDL 1.1 was a member submission done by Microsoft and IBM. Seven years later, WSDL 2.0 comes to see the light.

I mentioned before in this blog that WSDL offered four types of messaging, a combination of style/encoding parameters. There was an RPC style, and a Document Style, and for a backward compatibility, RPC could be Encoded or Literal.

Also, WSDL allowed a extension to define the transport, but it was just to say we were going to use HTTP, and that to send a SOAP structure as its payload. It was fixed to use the POST method, and it was also fixed the headers contents and such. Not much flexibility.

Well, WSDL 2.0 changes that. It now offers only one style: document. With that you can simulate your RPC calls if you want. Also, it allows to define the content of the document using an XML Schema, but that doesn't mean you will be sending XML through the wire (more on this later)!
But it doesn't stop there. WSDL 2.0 expands significantly the HTTP binding spec. Now you can specify if using GET instead of POST, indicate if you want you parameters (defined in the schema in types, remember?) to be encoded in the URL! Even, you can indicate that you want multi-part messages!

How friendly is that to REST? Keep on reading...

I know. Most of the REST community may hate anything that has to do with Web Services using its standards. But I feel that enterprise systems should not go in the wild with the REST complexity. Which complexity? you may say, if REST is the easiest thing. Well, yes and no. It is simple, but not easy. Everything has a complex component, and in REST it is the process of manually reading the contract and creating the interaction in code.

Yes, it is ok for simple parameter passing (two or three) even for some simple XML documents. But if you need to work with very complex XML and interactions, there may be a problem. Enterprise services may not be two or three parameters, and it may not be fine grained services. A way to describe all that so developers free themselves of understanding and coding XML to start thinking in business logic and processes, is a plus.

Will WSDL 2.0 that allows complex and simple things to be described, be a choice for that need of description? Who knows. What I know is that WSDL 2.0 seems to allow more Restful services descriptions, where they apply.

For more information about WSDL 2.0, please read the primer
For an article that explains Rest in WSDL 2.0 with more detail, please read this one from Eran

William Martinez Pomares.

Reference: WSDL 2.0 - a REST Friendly Language


  1. Hi William,

    >> What I know is that WSDL 2.0 seems to allow more Restful services descriptions, where they apply.

    You've made this point before. I agree wit you that REST is simple but not easy, especially if you try to adhere to the type of constraints that Roy describes here:

    I've struggled with REST and perhaps I don't understand it as well as I thought. Please give examples of applications where you think REST doesn't apply, and contrast that with those where you think it does.

    As far as I can tell Roy's main complaint is people not adhering to the constraint that hyperlinks should be the sole engine of application state, and that there should be no/little knowledge transferred between the client and server "out of band". Assuming that a WSDL is meant to be read by people, then the whole WSDL document is "out of band"communication and falls foul of Roy's constraints :)

    I can see that this is by far the best way to achieve the least amount of coupling between client and server, but without an intelligent client that can interpret the hypermedia sent back by the server I fail to see how this is practical.

    For Machine to machine interaction without the help of a human being to decide which link to follow, it sounds almost impossible. For me the best we can practically do is introduce a layer of indirection where concrete URLs are obtained through an alias in the media (such as an anchors id) that the client is hard coded to recognise and utilise.

    Have I missed something?



  2. Hi William,

    Sorry wrong link to Roy. Here is the one I meant to send:

    What's your take?



  3. Hi William,

    I've just thought about it and it all came flooding back. In Roy's dissertation he makes great play of self describing resources. Hypertext is self describing. You don't need an "out of band" description document, all you need is a "well-known" starting URI (home page), and you can explore the available links for yourself. Once you are happy that a certain sequence of requests (GET's, POST's etc) will deliver the required application behaviour, then you can choose to automate the process. If in the case of html, your script (client program) relies on stable element id's then the server is free to change the actual URI's of the resources as it sees fit.

    So on reflection Roy is right. REST doesn't need a WSDL (or a WADL for that matter), and if we are to take a strict interpretation of REST, then such things are anti-RESTful.

    The only question in my mind is how do you get to know the first starting URI? Now that's got to be communicated out of band right? :)

    All good stuff :)


  4. Hello Paul!
    Glad you find me again. I'm just moving from the old Blog for visibility, so I will keep both in synch.

    Ok, REST is hard to understand. Basically, in rest-discuss you will find several questions of the same issue: How do we eat the hypermedia driven thing.

    But, let's go back to web. In web, you, the user, use a browser, and you start with one URL. That will point to one resource, which representation is sent to the browser. That representation is HTML in type, so the browser renders it for you to see.

    Now, you read the HTML rendered page and see there is a menu. One option is "Gallery". YOu then think: Oh, a gallery, I may go and see some pictures.

    So, you click on Gallery, which is a link. That click is a get. That may bring a form for you to login. YOu enter you credentials and click on the button, and that sends a post. And then you get a picture, jpg, which is a resource's representation, which the browser renders as well.

    If you follow, you may, by now, have understood what a hypermedia driven thing is. But notice that out-of-band information is certainly not needed to follow it, but you actually need to understand what is meant by gallery and the login form. That information is shared knowledge, implicit in the application context.

    So, the first get brings a representation, rendered to the user, and the user understands, looks at the options and selects one to move to another state.

    Now, replace the user with an automated client. That client needs to understand the representation. If you need to pass the format of the representation to create the client, that may be out-of-band information. If you say the representation is application/javascript, that is an standard type and thus recognized, that means you won't need out-of-band info. See the difference? The standards media type helps you understand how to process the representation.

    Then, I get to WSDL or any other standard. It is a type, and you can "render" it. It can also tell you, without user intervention, what the options are, and how to proceed in the next step. SO answers try to use the HTML semantics. HTML is an XML standard too. BTW, WSDL contains information of services, plus the links to access them. Well use, I see no difference from any other format people use to define links and actions.

    What do you think?

    WIlliam Martinez.

  5. Hi William,

    >> What do you think?

    My gut reaction is that Roy needs to get his head out of the clouds and provide some concrete examples so that people know what he means :)

    I agree with your point that a WSDL can be self describing and can also be presented "in-band" so in a sense can be made to fall within the REST constraints. For me though there is a difference between the spirit of the law and the letter of the law. REST is a style, and the style is that you "discover" how the application works and what you can do through use. Web pages don't come with a "service description", at most you get a site index and that's it :)

    I'm sure if I think some more I'd come up with deeper insights, but my main thought right now is pragmatism. If I am producing a global public web service, then it should be fully discoverable. A home page that lists all the top level resources available, where I can link through and discover all the URL's (and parameters) open to me.

    If I am writing a RESTful interface for my own personal comsumption (I am the author of the client too), then I would skip all this discovery and define pretty RESTful URLs to the resources I want to expose and then take that knowledge "out of band" in my head across to my client implementation.

    As for the role of WSDL? Having come from a communications background, if I am going to rely on out of band information, then what I am doing is defining my own application protocol (use this URL to do this, send these parameters to do that etc). As such I would rather describe my protocol in plain English. I find plain English more expressive then XML and in general I don't believe in code generators, so why XML? :)

    I haven't looked at the latest WSDL spec in detail for a while so I'm no expert, and I'm sure this one will run and run. In the meanwhile pragmatic people like myself will be writing apps, doing what ever makes sense :)


  6. Hi William,

    >> But notice that out-of-band information is certainly not needed to follow it, but you actually need to understand what is meant by gallery and the login form. That information is shared knowledge, implicit in the application context.

    Just to be sure that we understand each other. I agree that the content of the hypermedia needs to be interpreted to follow the links. All the usual things apply like good names etc. A person will need to do the discovery for sure, using a shared understanding (like a shared comprehension of English or what ever other language is used to describe the links :))

    Once this discovery has taken place though, the human can go ahead and write a program against the same hypermedia. This was my point about stable id's in the media. When writing the client program the programmer will want to rely on certain aspects of the media that are deemed stable and unlikely to change. Without this, the client program will be brittle.

    So at best hypermedia aids discoverability by a human being, who can then automate the knowledge discovered. But programs can't be expected to discover things for themselves on the fly, they just lack the intelligence.

    I think we agree here, but I just wanted to be sure :)