This weekend I attended the "No Fluff Just Stuff" Software Symposium and had the good fortune of catching Scott Davis teach a session on "Real World Web Services." Scott is a terrific speaker and if you ever get the chance to listen to him, I highly recommend it - he is very entertaining and easy to listen to.

As noted by the title of this blog entry, I left the session very excited about an alternative style for constructing web services referred to as REST (stands for Representational State Transfer). The reason I'm excited is simple - I'm frustrated by the complexities of SOAP! Now, if you're thinking 'why is this guy frustrated? Building web services with SOAP is easy' let me burst your bubble: it isn't easy. Is it impossible? Of course not; is it complicated? Yes. I've recently been working on a project that utilizes SOAP based web services and I can tell you from personal experience it's not easy. Just to give you some background on myself, I am a Sun Certified Java Web Services Developer and it's still not easy. Consider this excerpt from the installation instructions for the Axis framework (a very popular web service framework):

Things you need to know before writing a Web Service:

1. Core Java datatypes, classes and programming concepts.
2. What threads are, race conditions, thread safety and sychronization.
3. What a classloader is, what hierarchical classloaders are, and the common causes of a "ClassNotFoundException".
4. How to diagnose trouble from exception traces, what a NullPointerException (NPE) and other common exceptions are, and how to fix them.
5. What a web application is; what a servlet is, where classes, libraries and data go in a web application.
6. How to start your application server and deploy a web application on it.
7. What a network is, the core concepts of the IP protocol suite and the sockets API. Specifically, what is TCP/IP.
8. What HTTP is. The core protocol and error codes, HTTP headers and perhaps the details of basic authentication.
9. What XML is. Not necessarily how to parse it or anything, just what constitutes well-formed and valid XML.

Axis and SOAP depends on all these details. If you don't know them, Axis (or anyone else's Web Service middleware) is a dangerous place to learn. Sooner or later you will be forced to discover these details, and there are easier places to learn than Axis.
Source: http://ws.apache.org/axis/java/install.html

I would argue there should be more on this list; for example, the other web service specs and SOAP itself. If this doesn't convince you that writing a SOAP based web service is difficult, check out an email Richard Monson-Haefal received regarding web services (if nothing else, you'll get a good laugh out of it). Richard Monson-Haefel's assessment of this email is it's "spot on"; this coming from a guy who wrote a book about web services! Here are some more thoughts from Richard Monson-Haefal regarding web services. This weekend however, Scott Davis said something that really hit home: "SOAP is the EJB of the XML world".

So, what am I really saying here? Am I advocating complete abandonment of SOAP based web services? No, SOAP is here to say; however, REST is a very simple web service style that you should consider when designing and building web services.

So, what the heck is a REST web service?

#1 - Requests utilize existing HTTP protocol infrastructure

Requests consist of basic HTTP requests and either query string parameters or a resource path; this is different than SOAP in that SOAP places an xml message in the HTTP request body.

#2 - Responses return very basic XML messages

Scott Davis referred to these XML messages as Plain Old XML (POX) messages which is analogous to POJOs. A great thing about this is the simplicity involved in the messages; DTDs or XML schemas are optional.

#3 - Think human-readable versus machine-processable

In a SOAP based web service, the web service itself is described by a WSDL document which allows for auto-generation of web service clients using Axis for example; however, in REST based web services there is no corresponding web service definition. This is a good thing in that it greatly simplifies things - no WSDL! (It isn't completely good though, auto generation of client code isn't possible.)

Closing Thoughts

When you think of REST, you should think simplicity and the KISS Principle. If you have a need for a very simple web service, then REST could be a very good option; if your needs are more complicated, then a SOAP based web service is probably a better option. If you want more info on REST, I encourage you to look in the following places - I am! (If you know of others, please share with a comment.)

• Building Web Services the REST Way - Roger L. Costello
• Real World Web Services - Scott Davis
• Architectural Styles and the Design of Network-based Software Architectures - Roy Thomas Fielding

Just one more thing Scott shared that I found fascinating. Amazon.com publishes their web services in both SOAP and REST versions. According to Tim Oreilly's article REST vs. SOAP at Amazon , 85% of all Amazon.com web service requests utilize the REST interface as opposed to the SOAP interface. Now, that's a very compelling case for REST web services!