Oscar Westra van Holthe - Kind

RESTful web services and applications

In this article, I'll be exploring the options of using REST in both web services and web applications. My goal: to determine how to fit this design principle into enterprise development. When programming in a job, this is what you do after all. For enterprise development demands the following from code:

Must support code generation for client code. The ease with which one can set up a first, running proof that you can connect to a web service and call a web method is a very compelling argument for WSDL, and against many REST implementations. If I can't make the first web service call in 5 minutes, I'll use WSDL instead. After all, business is interested in the bottom line, which (for software developement) means time to market. Period.

Yes, I know that time to market isn't always best served by this approach. But customers and managers demand it because it makes the product visible from scratch. Same as with building a boat, building or any other, fysical object: they can see the project slowly taking shape. This helps them understand what they otherwise could not.

REST and it's advantages

In 2000, Roy Fielding's dissertation on REST was published. Since then, it has not been met with widespread acceptance: it's often easier to stay in the procedural mindset and use WSDL web services, than it is to truly adopt an object oriented mindset.

But, I hear you saying, we already have object oriented laguages in widespread use since more than a decade! And you'd be right. But we have not seen a widespread adoption of object oriented design yet. Much of the code we see is still procedural in nature, violating the S.O.L.I.D. design principles of OO. Luckily this is not relevant for REST: all we care about is resource oriented programming. So we may still create an object, and POST it to a different object (our client stub of the web service) to create it.

For those who do use it, REST offers (among other things) these major advantages:

Implementing REST in web services

For implementing a RESTful web service in Java, there are Restlet and JSR-311. Several implementations of JSR-311 exist, most notably JBoss RestEasy and Glassfish Jersey). Both Restlet and JSR-311 have a serious drawback: it's about as complete as the latest servlet specification. Specifically, they provide no framework on how to define your data. Arguably, the most natural data format is not always an XML structure. But the XSD that WSDL uses at least defines something that I can have my computer generate the client code for. The WSDL is one command away from generated glue in any supported programming language. For REST, I'll have to roll my own (warning sign #1).

At the beginning, I said I need to be able to generate some code. With REST like web services, this will be the data structures I'll query & update. My choice for this is XSD, as it allows me to define all object structures I'm likely to encounter, and also because it's already widely known.

Staying in the strucure that Restlet and JSR-311 provide, I now need to implement the following:

As you can see, this last bit is not that trivial. At least it isn't if you realize that references to other objects are done by inserting their resource URL, so I can't use the default generated XSD from my domain model as-is. And I haven't even started about the fact that you're basically writing a framework – and that while Restlet and JSR-311 are meant to be that framework already. So my conclusion so far is that REST for web services in the enterprise currently (Januari 2009) a bridge too far.

Update: I know there exists a WSDL equivalent, WADL. However, I have yet to find a tool that generates the WADL from my code. Worse yet, an automatically generated description of my interface also isn't standardized yet.

Implementing REST in web applications

As we know, the web is not the internet. The web is accessible by a web browser, and as such imposes two important restrictions on a web application: HTTP & HTML. When we're talking about REST, this offers a big advantage in terms of ease of use and especially flexible interfaces.

The first thing to realize is that we need to relax the REST constraints: HTML only supports the HTTP request methods GET & POST, so all writing actions need to be tunneled over POST.

However, when we implement the Post-Redirect-Get design pattern in an action based framework, in combination with the small number of verbs in REST (List/Read, Save and Add item/action/...), we get an easy to build & maintain application. Some characteristics:

No duplicate submits
The biggest advantage of the Post-Redirect-Get pattern is that the redirect makes a duplicate submit on a page reload impossible. Combined with a simple javascript that forbids duplicate submits while the page hasn't reloaded yet, this makes duplicate submits a thing of the past.
Bookmarkability
Another advantage of the Post-Redirect-Get pattern is that of bookmarkability: each search and each resource is displayed in response to a GET request. Ideal for bookmarks.
One ActionBean per (set of related) page(s)
Each action bean is tied to one or more pages, and is the only one responsible for these pages. This works well, as actions are usually modelled as JavaBean objects, and it's properties correspond to the form fields on the page(s). When the number of properties is also intewntionally limited, this ensures that if the ActionBean is responsible for multiple pages, the pages will be related.
Easy managability of an ActionBean superclass, that handles the basic CRUD.
Because REST offers a limited number of verbs with similar functionality, it's easy to encapsulate the most used verbs (the CRUD functionality) into an (optionally abstract) superclass.

In effect, this means that web applications combine just fine with the REST philosophy. It makes the pages in a web application into bookmarkable resources, which makes the simplicity of early web applications easier to attain. This also makes an application easier to use.

Since each page supports basic CRUD (remeber the ActionBean superclass?), updating the data becomes easily understood: when authorized, it's always possible. Also, since each ActionBean is responsible for related pages, it becomes easier to ensure that all actions performed only have local effects. This is yet another part of your arsenal to make an application easier to use.

The only this that the technical aspects of the REST philosophy do not help with are the page and usability design. So be sure to consult a usability expert and graphical designer (in that order) to create an easy to use, friendly application.

Conclusion

As can be seen in this article, REST is a philosophy that makes developing and using a web application easier.

However, for enterprise web services it is a bridge too far. The biggest drawback is the lack of standardized tools for generating the model classes definition. XSD is simply not suitable out of the box, due to the use of resource URL's in the REST philosophy.