How does Apache Axis2 Differentiate SOAP from REST

Apache Axis2 supports both SOAP as well as REST. The default behaviour is that any service deployed on Axis2 can be accessed as using SOAP or REST style request. So how does Axis2 differentiate SOAP from REST request?

It first looks at the HTTP Method of the incoming request. If its GET, PUT or DELETE it is processed assuming its a REST request, but if its POST we need to do some checks. These include checking the content-type of the incoming request. SOAP 1.2 uses the content-type of application/soap+xml while SOAP 1.1 uses text/xml as its content-type. Hence using this we could differentiate SOAP request from REST style request. Does that mean that we are done? Well no. There is a little glitch though. The content-type text/xml is used to send REST (POX to be exact) style request as well. So if the content-type is text/xml we need to do further processing. The field we look for in such cases is the SOAPAction header. According to the SOAP 1.1 spec the SOAPAction header is mandatory (Its optional in SOAP 1.2 though). Therefore if a request comes in with the content-type text/xml that has a SOAPAction header it is treated as SOAP.

Podcast - Can WSDL 2.0 be used to describe a RESTfull service

In this podcast I talk about how WSDL 2.0 can be used to describe RESTfull services. I also talk about why one would want to describe a RESTfull service using WSDL 2.0.

In this podcast I mention about a couple of examples up on mooshup.com which shows how a RESTfull service can be described using WSDL 2.0. You could find more details about that example here.

Book on RESTfull Web Services with PHP by Samisa

Samisa Abeysinghe's book "RESTful PHP Web Services" is now available for Purchase. Learn the basic architectural concepts and step through examples of consuming and creating RESTful web services in PHP.


What you will learn from this book:

• Basic concepts of REST architecture
• Consuming public REST-style services from your PHP applications
• Consuming RESTful web services, such as those from leading APIs such as Flickr, and Yahoo Web Search
• Making your own PHP applications accessible to other applications through a RESTful API
• REST support in the popular Zend framework
• Debugging RESTful services and clients
• A case study of designing a RESTful PHP service from the ground up, and designing clients to consume the service

Approach:

The book explains the basic concepts associated with the REST architectural style, but the emphasis is on creating PHP code for consuming and creating RESTful services in PHP. There is plenty of example PHP code to illustrate the concepts, with careful explanations of how the code works.

Who this book is written for:

This book targets PHP developers who want to build or make use of RESTful web services, or explore the options available to them in PHP. You will need to know the basics of PHP development, but no knowledge of REST is assumed, nor any knowledge of creating web services generally.

The book also contains a dedicated appendix chapter on using WSO2 WSF/PHP.

Apache Synapse/WSO2 ESB calling a REST Endpoint

One of the features of Apache Synapse and the WSO2 ESB (Which is Apache Synapse + Monitoring + Management + WSO2 Registry Integration) is that it can change message formats.

There was a question on the ESB-USER mailing list recently asking how you could receive a SOAP message and send out a REST message (HTTP POST serialized as application/x-www-form-urlencoded) to another service. In order to do this you simply need to set two properties on the message. The HTTP_Method to be used and the messageType to be used. The following is a complete synapse.xml

<syn:definitions xmlns:syn="http://ws.apache.org/ns/synapse">

    <syn:registry provider="org.wso2.esb.registry.ESBRegistry">

        <syn:parameter name="root">file:registry/</syn:parameter>

    </syn:registry>

    <syn:proxy name="RESTProxy" startOnLoad="true">

        <syn:target>

            <syn:endpoint name="RESTEndpoint">

                <syn:address uri="http://localhost:7763/services/keith/test/foo"/>

            </syn:endpoint>

            <syn:inSequence>

                <syn:property name="messageType" value="application/x-www-form-urlencoded" scope="axis2"/>

                <syn:property name="HTTP_METHOD" value="post" scope="axis2"/>

            </syn:inSequence>

        </syn:target>

    </syn:proxy>   

    <syn:sequence name="main">

        <syn:send/>

    </syn:sequence>

    <syn:sequence name="fault">

        <syn:log/>

    </syn:sequence>

</syn:definitions>

Here is the request sent into the ESB:

POST /soap/RESTProxy/mediate HTTP/1.1

Content-Type: application/soap+xml; charset=UTF-8; action="urn:anonOutInOp"

User-Agent: WSO2 Mashup Server - Version 1.5.1

Host: 127.0.0.1

Content-Length: 191



<?xml version='1.0' encoding='UTF-8'?>

   <soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">

      <soapenv:Body>

         <foo>

            <param>keith</param>

         </foo>

      </soapenv:Body>

   </soapenv:Envelope>

Here is its response (or Request sent out to the REST service):

POST http://localhost:7763/services/keith/test/foo HTTP/1.1
Host: 127.0.0.1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8;action="urn:anonOutInOp";
Transfer-Encoding: chunked
Connection: Keep-Alive
User-Agent: Synapse-HttpComponents-NIO

b
param=keith
0

RESTful Web Services with Apache Axis2

RESTful Web Services with Apache Axis2 is powered by the WSDL 2.0 HTTPBinding, hence as of now (1.4.1 release of Axis2) users need to deploy there services using WSDL 2.0 to write truly RESTfull services in Axis2. I agree that there aren't too many people who are familiar with WSDL 2.0. Therefore I put together an article that helps you through the process of taking your Java code, generating a WSDL 2.0 from it and hand editing it to suit your needs. The article "RESTful Web Services with Apache Axis2" is now available on the WSO2 oxygen tank.

I plan on making it simpler to author RESTfull services in Axis2 in future.

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.

RESTfull Mashup with WSDL 2.0 - WSO2 Mashup Server

I was looking around for REST stuff related to Axis2 and stumbled upon one of Stefan Tilkov’s blog post (An old one at that). In that post Stefan had asked somebody to show a WSDL 2.0 document that describes this RESTfull scenario.

Too bad I didn't come across this back then, but as the saying goes better late than never. WSDL 2.0 can describe this scenario easily and I thought of writing a WSDL 2.0 document for this scenario (I've made one change to the URLS used in the scenario, instead of customer/{id}/orders I've used customerorders/{id}. This is not due to a limitation in WSDL 2.0 but rather the implementation of Axis2).

I put all these details together and built a little Mashup (which I named RESTDemo) that runs on the WSO2 Mashup Server. Of course the WSO2 Mashup Server has the ability to build RESTfull Mashups. In order to make it accessible to others I've uploaded it to Mooshup.com our community site.

Note : I have made some assumptions on how an Order and a Customer will be described. My assumptions is that an Order is described by an id (String), customerID (String), details (String), amount (Double), items (String array). A customer will be described as id (String), name (String), address (String), email (String).

The main objective of putting this Mashup together was to demonstrate that this RESTfull scenario can be described using WSDL 2.0. The WSDL 2.0 for this mashup can be accessed from the Mashup page, you could choose either the annotated view or the raw view.

The all important section in the WSDL is the HTTPBinding , cause this is where all the information for accessing this service via REST lies. Ideally I would have loved to make the content-type (whttp:inputSerialization in WSDL 2.0 terms) of a few of the operations application/x-www-form-urlencoded (WSDL 2.0 defaults it to application/xml) . But unfortunately as of now the Mashup Server does not offer a mechanism to do this. I've already opened a JIRA so that this could be added.

You might also want to try out our RESTfull mashup. Simply goto its tryit page in order to try it out (The tryit page allows you to test your mashup and a drop down at the top allows users to select the endpoint they want to access, in our case we may prefer to choose the HTTPEndpoint cause this is all about REST). Now this is where the benefit of a standard description (WSDL 2.0) for our RESTfull mashup kicks in. The tryit page is auto generated off the WSDL 2.0 doc (It has all the information as to how this mashup can be accessed, let it be SOAP 1.1, SOAP 1.2 or REST). The tryit page invokes the service using a auto generated JavaScript Stub.

Let me now explain as to why I had to change the URL mapping for get all customer orders. Axis2 (Which is what the WSO2 Mashup Server is built on) dispatches to the correct operation (when REST is used) using the http method and the URL of the request (The service is always found using the request URL). Now when we try to figure out the operation the request is headed to we basically do some pattern matching, and thats done against the first constant part we get off the httpLocation. In the scenario given it allows a GET on customer/{id}/orders as well as customer/{id}. Now if I used these two templates as it is, there would have been dispatching issues, hence I decided to change the second template.

This has become quite a long blog post. If you are interested in knowing how WSDL 2.0 can be used to describe RESTfull services stay tuned to my blog. I plan to write more on this topic in the time to come. Also there is a RESTfull services on Axis2 tutorial which is just around the corner.

Note : Mooshup is running the 1.5.1 version of the WSO2 Mashup Server (released before Axis2 1.4.1). There fore its REST URLs are of the format http://mooshup.com/services/keith/RESTDemo.HTTPEndpoint/customer/123, in the next version which will be based on Axis2 1.4.1 the URLs of the form http://mooshup.com/services/keith/RESTDemo/customer/123 would also work.