Runtime linking in RESTful apps can reduce client-server coupling as the server can tweak the workflow at runtime without completely breaking client apps. Here is one more reason to switch from static pre-published URIs to runtime linking.

Say, you built a cool Web API. Folks are excited about your API are are actively using it. You now have some better ideas, and want to find the effectiveness of some options you have. How do you go about testing the effectiveness of each option before flipping on the big switch?

For consumer-facing web apps, A/B testing provides an effective technique for segmented testing of various design/implementation options. Here is one simple way to build hooks for A/B testing into web pages.

  // Embed test variables into links.

  trackId = createLink(<some ID>, <some test variables>);

  // Store test variables for later analysis

  storeTest(trackId, <test variables>);

  // Render link

  ... + "&track=" + trackId + "...";

This may produce a URI like the following.

  <a href="http://example.org/blahBlah?someParams&track=xyz>...</a>

Subsequently, when a user actives this link, the server can correlate that link to the test variables used. This correlation data forms the basis for post-hoc analysis for A/B and other forms of bucketed testing.

By using runtime linking for Web APIs, i.e., by making them take advantage of the HATEOAS constraint of REST, we can use the same technique for correlating API calls to test variables and conduct A/B testing. That is, when clients are discovering URIs at runtime based on known link relations, servers have a chance to get smarter.

This post is in response to Sameer Tyagi‘s article on using JAX-WS for RESTful web services posted at the Sun Developer Network. I find a few points stated in this article troubling if not inaccurate – (a) it presents REST in a limited scope thereby showing SOAP in better light, and (b) it misses some key differences between REST and SOAP based web services. Beyond this, the example cited in this article just shows why you SHOULD NOT use JAX-WS for REST style web services. In this post, I would like to discuss the whys behind the two statements I just made.

Let me first list each point mentioned about when to use REST and when to use SOAP, and comment on each. The statements in italics below are from this article.

1. Use REST when the web services are completely statelesss.

   This article contents that REST is suited for stateless services. To the contrary, most people prefer keeping SOAP style web services stateless. I also find it easier to manage state over REST based services than SOAP based services. With REST based services, you can either manage state with cookies or with the state encoded in the URI. With SOAP based services, the only option is to encode the state within the envelope.

2. Use REST when bandwidth is particularly important and needs to be limited.

   REST based web services may be less-bloated. That may or may not turn into better performance – it depends on the network and the latency.

3. Use REST for web service delivery or aggregation into existing web sites … using technologies such as Asynchronous JavaScript with XML (AJAX).

   This point is a stretch for two reasons. It is equally possible to invoke SOAP style services via XMLHttpRequest. There are pros and cons to each approach. Secondly, I would not use JAX-WS for driving Ajax responses as using JSON over XML has several advantages and JAX-WS is not meant for anything other than XML.

4. Use REST when the service producer and service consumer have a mutual understanding of the context and content being passed along and use SOAP when a format contract mus be established to describe the interface that the web service offers.

   Both the statements are misleading. I think these statements are based on the assumption that WSDL and schemas provide such a contract for SOAP based web services. This is only half-true. WSDL and schemas can describe the structure of messages (data, headers, faults etc.), but you still need to describe the semantics of operations and messages outside the WSDL. Without a description of those semantics, it is not difficult for different people to come up with different interpretations. WSDL and schemas don’t describe the semantic meaning.

5. Use SOAP when The architecture must address complex nonfunctional requirements such as Transactions, Security,
   Addressing, Trust, Coordination, and so on that go beyond simple CRUD operations possible with REST.

   This article contends that real enterprise applications need more than the CRUD operations that are possible with HTTP. Actually, this article starts by saying how HTTP is related to SQL for CRUD capabilities. This is nothing but a mis-interpreation of HTTP. HTTP defines some standard verbs with defined semantics. There are two ways you can use HTTP for REST style services – by encoding the operations in the URI, and/or by defining new verbs. This gives a wide range of possibilities for surfacing services – definitely not limited to CRUD. In any case, how is this better than encoding the operations in the header/body of a SOAP message and send all messages via POST?

   Regarding the non-functional requirements such as Transactions, Security, Addressing, Trust, and Coordination, except for security, we are yet to see any one using the others seriously today. Who said security cannot be addressed with RESTful web services?

What this article forgets to mention is that RESTful services don’t hide the fact that they are operating over HTTP, where as SOAP style services try to hide this and encourage protocol agnosticism. The result of this protocol agnosticism is API bloat with too many indirections. I have been developing web services for over three years, and I don’t have problems with the lower level APIs (SAAJ, DOM etc.) – what frustrates me is the bloat added by the higher-level APIs (dispatchers, handlers, XML binding etc.) trying to hide the protocol.

JAX-WS for RESTful Services?

JAX-WS (like its dead-cousin JAX-RPC) is designed with protocol abstraction in mind – so they carry the bloat I just mentioned. The API goes on to great trouble in hiding the protocol with layer upon layer – may be the thought was if there are too many layers on top of the protocol, nobody would notice the protocol?

Yes, you can use JAX-WS for REST style services, but as I show below, using JAX-WS makes your code inherit some of that bloat. It adds more complexity without necessarily offering any advantages. Note that the example in this article uses JAXB in combination with JAX-WS, and my comments are limited to using JAX-WS.

First, let me briefly describe the example provided in this article.

1. A purchase order service to get, create, update, or delete purchase orders. This service is implemented using the
   javax.xml.ws.Provider interface
   and some annotations of JAX-WS. The invoke() of this class method processes the request by first checking the request
   verb and the path of the URI used to make the request.
2. A client that uses the javax.xml.ws.Service
   and javax.xml.ws.Dispatch
   interfaces of JAX-WS to talk to the purchase order service.

This example is simple, yet demonstrates the bloat very well. Let’s see the bloat.

1. The servlet API is best suited for providing an entry point for REST-style services. The API has the right abstractions for serving services over HTTP. But since JAX-WS wants to stay protocol agnostic, there is no way you can bind JAX-WS provider classes to servlets. But still JAX-WS leaks some protocol details via the javax.xml.ws.handler.MessageContext
   (which IMO, makes JAX-WS more usable than JAXRPC). So, this example ends up using the leaks to get details of the request API.

   public Source invoke(Source source) {
   try{
   MessageContext mc = wsContext.getMessageContext();
   String path = (String)mc.get(MessageContext.PATH_INFO);
   String method = (String)mc.get(MessageContext.HTTP_REQUEST_METHOD);
   System.out.println("Got HTTP "+method+" request for "+path);
   if (method.equals("GET"))
   return get(mc);
   if (method.equals("POST"))
   return post(source, mc);
   if (method.equals("PUT"))
   return put(source, mc);
   if (method.equals("DELETE"))
   return delete(source, mc);
   throw new WebServiceException("Unsupported method:" +method);
   } catch(JAXBException je) {
   throw new WebServiceException(je);
   }
   }
   

   The above code from this article makes a good case why you should servlet API and not JAX-WS. Since this service is bound to HTTP, this code had to obtain the request info directly via the leaked abstractions. Here is how you could rewrite this using the servlet API.

   
// Nothing


   Except for message parsing, there is no need to write code to detect the verb. The good old javax.servlet.http.HttpServlet does this job, and would delegate to methods like doGet(), doPost() etc.

2. The purchase order service writes back fault messages and response error codes. Here again, we see the SOAP concepts leaking into the REST-style purchase order service.

3. The client side code is similarly more complex like the service implementation. The client first creates a Service, adds a Port, then creates a Dispatcher, creates a RequestContext, and then invokes the service.

   private  void retrieveOrder() {
   service = Service.create(qname);
   service.addPort(qname, HTTPBinding.HTTP_BINDING, url + "ABC-123");
   Dispatch dispatcher = service.createDispatch(qname, Source.class, Service.Mode.MESSAGE);
   Map requestContext = dispatcher.getRequestContext();
   requestContext.put(MessageContext.HTTP_REQUEST_METHOD, "GET");
   Source result = dispatcher.invoke(null);
   printSource(result);
   }
   

   There are too many abstractions in this code snippet. It uses APIs designed for SOAP and WSDL to implement REST-style invocations. But why not use HttpURLConnection for the same task?

   // pseudo code
   URL url = new URL(...);
   HttpURLConnection connection = (HttpURLConnection) url.openConnection();
   connection.setDoInput(true);
   connection.setRequestMethod("GET");
   // ...
   InputStream is = connection.getInputStream();
   // Read and bind to a JAXB object
   

   This code is not trivial either, but you are atleast dealing with HTTP directly – no SOAPy abstractions in the way of doing REST.

Due to the fact that JAX-WS hides HTTP, you will also notice that neither the client nor the service can easily deal with things like headers and cookies. This article makes a good point that REST style services can take advatange of HTTP caching, but unfortunately, JAX-WS won’t let you do it easily.

My Conclusion

In summary, this articles makes an attempt to justify that JAX-WS can beused for programming REST-style web services. It should also have
taken the time to justify why you must use JAX-WS as opposed to, let’s say, servlets and a HTTP client?

If the JAX-WS API is really intent on supporting REST-style programming, here are some the things that it needs to do

1. Provide an easier way to process XML and JSON messages on the server side without hiding HTTP, preferrably by extending the servlet API.
2. Provide an wasier way to write HTTP client by creating some light-weight abstractions on the top of HttpURLConnection so that writing XML to, and reading XML from HTTP connections is simplified.

As of today, I would not recommend using JAX-WS for REST-style web services.

Update (09/03/2006): I just came across Mark Baker’s interview at http://www.infoq.com/articles/mark-baker-REST. In response to a question on combining REST with more conventional web services approaches, he says it’s technically possible, but from what I’ve seen of Web services toolkits (even those that claim to “support REST”), there’s a very good chance that it’ll be more trouble than it’s worth. That says it all.

Angle brackets or annotations? Is JAX-WS over-engineered or does it simplify web services development? I am disappointed with the points made by Richard Monson-Haefel and Jason Greene in their challenge and retractions against how complex or easy it is to use JAX-WS. Both their posts were provocative, but sidestep most of the requirements of complex web services. IMO, their positions are at the extreme ends.

For of all, let me look at Richard’s arguments. He complains that JAX-RPC and JAX-WS are over-engineered. He blames the API for its complexity. He blames features like handler chains. He complains that deployment is hard. These complaints are a bit disappointing. Given his expertise as an author of a book on J2EE web services, I would expect him to provide more
concrete criticism, and concrete proposals to address these limitations. Both were missing in his post. On the other side, Jason Greene tries to prove that it is trivial to write a web service using annotations. But I think his example actually proves Richard’s point that,
for the simplest services, JAX-RPC and JAX-WS work fine. His example does not get into any details of real-world complex web services.

On a scale of 1 to 10, I would give JAX-WS at least a 7 (I would have given a 9 had JAX-WS retained backwards compatibility with JAX-RPC). Here is my take on how JAX-specs scale for developing complex web services.

XML First

I would never start designing a web service in Java or some other
programming language, unless, of course, I’m doing a quick demo. Why?
Because, to design inter-operable and loosely-coupled web services, I need
to focus on the wire format first. Mapping to a programming language comes
later. During design, I need to focus on what kind of messages need to be
exchanged, what pieces of data need to be exposed and accepted, and their
detailed semantics. I also need to focus on the kind of faults need to be
returned, and their semantics. In essence, I would focus on a message
exchange protocol for each service.

To do all this, starting from Java with some annotations is not necessarily the best
approach. Such an approach would steal the focus away from the wire format
towards programming details such as class names, class hierarchies, method signatures, exceptions, etc.

To do this effectively, I need an XML-to-Java binding model that maps the
XML well-enough. With the help of JAXB, JAX-WS does a decent job in providing such a binding.

Injection of Services

The next important thing for me is the ability to inject services.
Take, for example, adding a security token to an outgoing message, or
processing a security token on an incoming message. The best way to do
this by adding handlers. Handlers are pluggable, can be inserted and
swapped as required without changing your application. I don’t understand
Richard Monson-Haefel’s complaint on handlers. At BEA, we use handlers to
drive a variety of use cases for our WSRP runtime.

I do have two complaints about handlers. Firstly, the criteria to inject
handlers is very coarse. Although JAX-WS improves upon JAX-RPC by letting
you specify service name patterns, protocol bindings etc., it is still too
coarse. I like to be able to specify handlers with some filtering criteria
using XPath or XQuery. My second complaint is about the underlying SAAJ,
and its tight-coupling to Java Mail and Java Activation Framework. SAAJ, by itself,
is fine, but I get jittery when it starts jumping to Java Mail API for
processing attachments. The programming model is not intuitive, and takes
some expertise to use it correctly.

JAX-WS needs further refinements in this area.

Services without Java Binding

JAX-WS adds support for building web services without requiring Java binding. I consider this to be a very important improvement over JAX-RPC. Both JAX-RPC and JAX-WS spend a lot of energy bridging between WSDL and XML and Java classes and methods. This is not necessarily the wrong approach, since it covers most of the use cases. However, for really performance conscious web services development, it is better to program to the XML directly. For instance,
instead of letting the container to unmarshal XML into Java beans, it may
be faster to proces the raw message directly. JAX-WS let’s you do this with the javax.xml.ws.Provider interface. The provider can receive SOAPMessage or a raw StreamSource

Performance is not the only use case for using providers to build web services. Another key use case is versioning. Direct access to the SOAP message gives more flexibility to create web services that can support multiple versions of web service. Working at this level requires some expertise since you need to be aware of angle brackets, DOM gotchas, namespace prefixes etc, but it is exciting to see this as a possibility with JAX-WS.

Protocol Handlers

This is yet another improvement in JAX-WS over JAX-RPC. Let me elaborate. In JAX-RPC,
handlers are protocol agnostic. Handlers don’t know anything about the
network protocol that was used to transport a message. On the server side,
handlers don’t know anything about the container that was used to run the
service. For purity sake, you might argue that all web services code must
be protocol independent “don’t care how the message got delivered – just
process it”. This may be the case for most web services, but definitely not
all web services. In real-world, web services co-exist with other apps
bound to various network protocols, and in some cases, we need a way to
peek into or influence protocol-specific aspects. Take, for example, any
WSRP producer implementation. For starters, a WSRP producer is a web
service that can be used to view/invoke portlets. In the J2EE world,
portlets mostly run on top of the servlet container. For a WSRP producer
to be able to interact with the servlet runtime, it needs access to
servlet request and servlet response. So, most WSRP producer
implementations out there use some internal/proprietary APIs to get hodl
of these objects from the servlet container. This is just one example.

JAX-WS has the notion of protocol handlers that can get more direct access to protocol level objects such as request and response headers, servlet-container variables like ServletContext, HttpServletRequest, HttpServletResponse, HttpSession etc.

My Summary

Overall, I think JAX-WS is great improvement over JAX-RPC. I take the side of Jason Greene, but not just for annotations. JAX-WS gives me access to more low-level stuff, and I now have less number of reasons to write my own web services stack – which I had to do a couple of years ago since JAX-RPC did not give me all that I wanted.