Welcome to EMC Consulting Blogs

This is the third part in a series on Representational State Transfer (REST). The first part makes an attempt at a proper introduction to the principles of REST. The second part discusses about how these principles are applied on the Internet for human consumption (the Human Web) and how they can likewise be applied to computer systems (the Programmable Web). In this instalment, which Ive broken up into two sub-parts, I want to share a fictional need for a service and then proceed to analyze the requirements and implement it in such a way that caters to both the Human and Programmable Webs. In this sub-part, well go over the requirements for the service and then make an attempt at a design. In the second upcoming sub-part, well implement the thing. Sounds groovy, eh?

While it is not required, I strongly suggest reading the other instalments first, so that a lot of the design decisions I make here make sense. It is my hope that you enjoy the ride as much Im going to enjoy sharing it.

Requirements

This is our mission, if we choose to accept it:

Armed with the power of Java, XML and REST, we should be ready. Lets get to task. We accept!

Analysis and Assumptions

These requirements are a bit vague, but we can extrapolate some key ones:

• Greeting service
• Customisable greetings
• Human friendly
• Machine friendly, different languages

We're also going to build our solution using the following tool set, which is easy and familiar to me:

• Java
• Java Enterprise Edition (J2EE)
• Hypertext Mark-up Language (HTML)
• Extensible Mark-up Language (XML)

Although we won't be thinking too heavily into technology at this point, it's good to set these assumptions in place, as it will influence how we tackle some of these issues.

Service Design

For the Greeting Service, well define an Interface with a function that will return an appropriate greeting for the holidays. To provide customizable greetings, well add another function that takes a name as input and returns the same appropriate greeting for the holidays but personally addressed as well. Well also define one model object, the greeting itself, with one property that will contain the greeting message.

I'll provide two implementations for my service. The first will be a simple implementation, returning a simple holiday greeting according to some set business rule we can define as were writing the code. The second will be my RESTful machine-friendly implementation. It will have a private method to somehow get an XML version of a greeting from a URI over HTTP and use a generic XML encoder/decoder class that we can provide to handle the greeting serialisation to and from XML.

Now that I think about these concerns with XML, Ill also add some methods to the greeting model object so that I can easily get an XML representation from a greeting object, as well as add a factory method that would create a greeting object given an XML representation of one. Of course, just like my RESTful greeting service implementation, Ill use the same generic XML encoder/decoder class to provide seamless integration.

Those pieces will finish the service side of our task. Heres a UML diagram to help us keep track:

Web Application Design

With our service design completed, we know have to think about how were going to expose our service to our human and machine audiences. The MyGreetingService implementation works well if you use Java, but our human audience for the most part does not do so directly. Furthermore, the GreetingServiceClient implementation will only work if theres a URI to use in the first place that would return the XML representation of a Greeting.

The answer, given our toolbox, is to create a J2EE Web Application to expose our service as both human readable and machine readable. We can leverage the popular Model-View Controller (MVC) design pattern with J2EE to create a nice system that can handle requests for both the HTML and XML versions of our greeting. Lets start by specifying the following two URIs for our representations[1]:

/greeter-service/greeting.html (human readable)
/greeter-service/greeting.xml (machine readable)

We can then map these URI patterns to an HTTP Servlet[2] that will act as the Controller in our design. We could make an abstract HTTP Servlet that handles the business of getting the greeting, and we can create two other Servlets that extend the first one, each returning a different representation, one thats HTML and one thats XML. That way we can map each URI variant to its own HTTP Servlet while reusing the code that does the business of getting the greeting. The HTML Servlet can pass the Model (Greeting) to the Java Server Page (JSP) to generate an HTML View. The XML Servlet can use the functions we defined on the Greeting object to generate an XML representation of it as an XML View. And because the requirements only call for receiving a greeting, well implement the doGet(HttpServletRequest, HttpServletResponse) function on the requisite Servlets to support HTTP GET. (In a future post, Ill go full-bore on supporting all HTTP methods for a purely RESTful service that supports reads and writes.)

Those bits help us wrap up the web application side of the story. Lets draw up some more UML to not lose track of these design decisions[3].

Before I finish the design, I’ll add scope for one more item. It would be really cool if we had a simple application that used our GreetingServiceClient (RESTful) implementation, which does our HTTP calls to our XML version of our resource. We’ll call it GreetingServiceApplication and implement its main function to utilize our service client. This would be analogous to the web browser for the HTML representation, but programmatic. To be consistent, let’s throw one more UML diagram up illustrating these bits as well:

Service Use Case

With the service and web application designs in place, let’s quickly illustrate at a high-level how our service works. Ideally, we want our consumers to make a request of the URI that’s appropriate for who they are (humans through web browsers would request greeting.html while machines would use the client we provide, or otherwise make a request directly to greeting.xml). All requests are made over HTTP using the appropriate URI for the resource they want.

This should work very well. I’m pleased with this design. We’re satisfying the requirements in a simple and RESTful way. Now we’re ready to dive into the code and make this happen.

Conclusion

Thinking RESTfully, we have designed a service and how we can expose it to different client types. For our human consumers, we can whip out some lovely HTML that they can see through their web browsers. For our machine-based consumers, we will provide an XML representation instead, and will include a client library to make things slightly simpler for our Java-based machine consumers.

In the second part of this instalment, we’ll proceed to implement this stuff. We’ll write plenty of code, and go through it bit by bit to explain why we do things the way we do. We’ll even test it out, so everything will really shift from the theoretical to the practical. Hopefully along the way you’ll pick up a thing or two on how to best implement your own RESTful services. It will be fun to do it, so I hope you come back. See you then!

[1] Another approach would be to have one URI (since it’s really one resource) and use the HTTP specification to communicate to the server who the requester (or User Agent) is, creating the appropriate response according to who’s requesting. However, I like this explicit approach better because a) not everyone specifies “who” they are, and b) the URI’s map more cleanly to what you are getting for them.

[2] An HTTP Servlet allows a software developer to add dynamic content to a Web server using the Java platform.

[3] We may be designing a bit much up front, but I like to plan ahead like this, allowing myself to change my mind at any time as I make discoveries in the trenches.