REST and WSDL 2.0 Discussion continues

In response to my blog post on using WSDL 2.0 to describe RESTfull services and Sanjiva's challenge Stefan has put forward 5 questions for me. Here are the answers to them.

Question: How does one one describe representation formats other than XML?
Answer: This can be done using the whttp:inputSerialization (for input messages), whttp:outputSerialization (for outgoing messages) and whttp:faultSerialization (for outgoing faults). The WSDL 2.0 Adjuncts spec defines three types of serializations. They are application/x-www-form-urlencoded, application/xml and multipart/form-data. Axis2 supports all three of these as well as JSON messages (This is how you can send JSON messages using the Mashup Server). At WSO2 we are considering doing a JSON binding for WSDL. If we had that in place even this could be described in a standard manner.

Question: How is content negotiation supported?
Answer: WSDL cannot describe this (neither do I expect it to), but we do have content negotiation support in Axis2. Due to some practical limitations we had to make it an optional feature. This can be made available by adding the following parameter to the axis2.xml.

<parameter name="httpContentNegotiation">true</parameter>


Question: How does one describe whether a URI parameter is a query parameter, path element, or matrix parameter?
Answer: There are a few properties and defaulting rules that help you achieve this. As my example shows parameters can me made to go in the path or query section using templates. An example template for sending the parameter "name" in the path segment would be "student/{name}" while sending a parameter as a query parameter would be "student?name={name}". This section in the adjuncts spec give a brief idea as to where the parameters not cited would appear. If application/x-www-form-urlencoded serialization is used on a GET all parameters not cited in the template would go in as query parameters. There is a additional property in WSDL 2.0 that helps you control this too. If you specify whttp:ignoreUncited="true" then all uncited parameters will be dropped.

What do you really mean by matrix parameters?

Question: Is there a way to describe response codes?
Answer: WSDL 2.0 does not allow you to specify the http response code of a outgoing message. Too bad we missed this (I wonder whether the working group had discussed this issue though). I guess this is the one thing that WSDL 2.0 missed. Hence I opened a issue against the spec. But WSDL 2.0 allows you to set http codes on fault messages. For e.g on a fault you could say whttp:code="402".

Question: What about describing hypermedia? :-)
Answer: In my example you would have noticed that I actually return a set of links to where the actual resource exist when invoking some operations. For e.g getAllCustomers would return links to the actual customers. I agree that there is something missing in here, a way to describe that accessing this link returned, would fetch you the customers details (Probably an annotation in the schema could describe this).

Stefan had mentioned the following in his post

"One of the interesting aspects is the try out page, which is generated from the WSDL. Essentially this means that metadata is used to generate the self-descriptive form; somewhat backwards from a REST perspective, but understandable given that the goal was to have an external description in the first place."

Yes the WSDL captures all the metadata of your service. Don't you think that there is a definite advantage in having a standard description for your service? This would enable users to build tools that would make life easy when accessing such services. The tryit is an good example of this. You could even build a UI for a service using a generated JavaScript stub. The UpgradeChecker sample on mooshup is a good example for this.

Its good to have a constructive discussion around REST, SOAP and WSDL rather than try to proclaim that one of them is the way to go and the other does not have a place.