In a previous blog  you learned how to build RESTful web services using Spring, now we are going to show you how build a client to access RESTful web services using Spring's RestTemplate.  The RestTemplate was introduce in Spring 3.0 and can be used right out the box by including the org.springframework.web jar in your classpath.  The RestTemplate provides entry points for the six main HTTP methods:

Http Method	RestTemplate Method
DELETE	delete(String, Object...)
GET	getForObject(String, Class, Object...)
HEAD	headForHeaders(String, Object...)
OPTIONS	optionsForAllow(String, Object...)
POST	postForLocation(String, Object, Object...)
PUT	put(String, Object, Object...)

The method names indicate the HTTP method that they will invoke and the second part of the name indicates what the method will return.  The first argument of each method is the URI.  The URI can either be a URI template or a normal URI.  I am going to show you how to use the RestTemplate to access the dictionary service that was introduced in a previous blog .

GET

To retrieve all the words out of the dictionary we use the following code:

RestTemplate template = new RestTemplate();
WordList wordList = template.getForObject("
    http://localhost:8080/SpringDictionaryService/bti/dictionary", 
    WordList.class);

To retrieve a word:

Map vars = new HashMap(); vars.put("word", "set");
Word word = template.getForObject(
     "http://localhost:8080/SpringDictionaryService/bti/dictionary/{word}",
      Word.class, vars);

This method uses a URI template and takes a Map which contains the URI path variables. This same example can be done using a normal URI:

RestTemplate template = new RestTemplate();
Word word = template.getForObject(
     "http://localhost:8080/SpringDictionaryService/bti/dictionary/set",
     Word.class);

POST

To add a new word to our dictionary we use the following code:

Word newWord = new Word("BTIer", "A great teammate");
URI resourceLocation = template.postForLocation(
     "http://localhost:8080/SpringDictionaryService/bti/dictionary/",
     newWord); 

The above code will add the word "BTIer" to the dictionary with the definition of "A great teammate". The postForLocation method returns a URI which gives the location of the newly created resource. The URI for this newly added word is "/SpringDictionaryService/bti/dictionary/BTIer".

PUT

To update a word in our dictionary we use the following code:

Word newWord = new Word("BTIer", "The ultimate teammate");
template.put(
     "http://localhost:8080/SpringDictionaryService/bti/dictionary/BTIer",
     newWord);

DELETE

To remove a word from our dictionary we use the following code:

template.delete("http://localhost:8080/SpringDictionaryService/bti/dictionary/BTIer");

As you can see Spring provides an easy way to create clients to access RESTful services using the RestTemplate. With the ability to also create RESTful services easily, Spring is a great framework for both implementing and consuming RESTful services.

In this blog we are going to take a look at clients of RESTful Web Services. RESTful Web Service clients are programs or libraries that can be used to consume RESTful Web Services. These clients are responsible for making the underlying HTTP requests to a RESTful Web Service. Every modern programming language has one or more libraries for making HTTP requests and each client will usually use one of these libraries.

To build a RESTful Web Service client you will need an HTTP library with at least these features:

• Supports GET, POST, PUT, and DELETE requests: These four http methods are required when creating and modifying resources.
• Supports adding and modifying request headers: Specific request header values need to be used to specify the representation of the resource (json, xml, jpg, etc).
• Allows the programmer to customize the data sent as the entity-body of a PUT or POST request: This means that the programmer can include any data they want in any representation they choose as the body of the request.
• Allows the programmer access to the response code and headers: The programmer needs access to the response code to determine if the request was processed successfully or if any error conditions exist. Access to the header is used to determine the representation of the resource in the response body.
• Supports HTTPS and SSL certificate validation: This ties in with security as many RESTful Web Services and http servers in general will require the client to support secure communication.

Example Libraries

Some example libraries that support these features are as follows:

• Java: Spring's Rest Template, Apache HttpClient
• Ruby: ActiveResource
• Javascript: Many solutions (XMLHttpRequest, ExtJs, jQuery, Dojo, Prototype, etc)
• C++: Curl
• .NET: HttpWebRequest and HttpWebResponse

Once you have an acceptable HTTP library, you will need another library or piece of code to convert your resource into the chosen representation and vice-versa. The most common representations currently used in RESTful Web Services are XML and JSON.

In our next blog post we will take a closer look at some of the libraries programmers use in their RESTful Web Service clients and dig into some examples.

The Spring Framework is the current dominant JEE framework.  Spring allows you to expose legacy web applications as Web Services without changing much code.  This post will describe what you need to create a RESTful Web Service in Spring.  This information reinforces the topics introduced in the "Building RESTful Web Services with Spring" screencast.  

First, add two tags to the servlet configuration file:

<context-component-scan base-package='org.bti'/>

This tag enables auto-detection of annotated components, such as @Controller and @Repository, in the package specified by the base-package attribute.  Then the following tag:

<mvc-annotation-driven/>

Using this tag is the best way of jump starting a Spring MVC project.  This tag does all of the following:

• Registers the DefaultAnnotationHandlerMapping and AnnotationMethodHandlerAdapter beans which are required for Spring to dispatch requests to @Controller annotated classes.
• Registers those beans to use JAXB to read and write XML and Jackson to read and write JSON if JAXB and Jackson are in your classpath.
• Registers other converters to convert different number formats and date/time formats.

Spring implements RESTful Web Services by mapping HTTP requests and methods to Controller methods using custom annotations.  Here's a look at these annotations:

• @Controller – Let's Spring know that this class will serve as a controller in the MVC pattern. Spring will search these classes for methods annotated with @RequestMapping.
• @RequestMapping – Used to map URLs onto an entire class or method. If the annotation is used at the class level @RequestParams can be used to narrow the mappings. Mappings can also be narrowed by the request method (GET/POST/DELETE/PUT)
• @PathVariable – Used to map variables in the URI in the @RequestMapping to method parameters

In addition, there are many other types of advanced mappings for the @RequestMapping annotation:

• @RequestBody – Used to map the request body onto a variable.  Can also map to Beans such as our Word object, using either JAXB or Jackson to convert the data from either xml or json.  Uses the content type to determine the format.
• @ResponseBody – Used to let Spring know that you want whatever you are returning from the method to be written to the response, and the response status will be OK by default.  The output format depends on the Accepts header of the request.
• @ResponseStatus – Lets Spring know what status to write to the response.
• @ExceptionHandler – Tells Spring that a type of exception thrown in a controller should be handled by the annotated method. Used along with @ResponseStatus, this annotation also gives the ability to have a request return different statuses based on the outcome of the request.
• @RequestParam – Maps a request or query parameters to method parameters.

This is just a brief overview of building RESTful Web Services with Spring.  If would like more information please check out the "Building RESTful Web Services with Spring" screencast series.

BTI has just released the third and final video in a series of screencasts introducing the audience to the RESTful capabilities of the Spring Framework. Part 3 covers PUT and DELETE functionality.

BTI has just released part two in a series of screencasts introducing the audience to the RESTful capabilities of the Spring Framework. Part 2 introduces the ability to make GET requests to our RESTful web service.

BTI has just released part one in a series of screencasts introducing the audience to the RESTful capabilities of the Spring Framework.