In this blog we are going to take a look at building a RESTful Web Service client with Apache HttpClient v4. Previously we have blogged and created screencasts using Jersey, Spring, and Spring’s RESTTemplate to show examples of building RESTful Web Services and clients. Apache HttpClient is the client implementation of the HTTP spec that is built on top of the java.net classes.

The following are some features of Apache HttpClient version 4. You can check out the full feature list and API on the homepage.

• Standards based, pure Java, implementation of HTTP versions 1.0 and 1.1
• Full implementation of all HTTP methods (GET, POST, PUT, DELETE, HEAD, OPTIONS, and TRACE).
• Supports encryption with HTTPS (HTTP over SSL) protocol.
• Basic, Digest authentication schemes.
• Plug-in mechanism for custom authentication schemes.
• Direct access to the response code and headers sent by the server.

Today we are going to focus on the parts of the API that allow you to build a client for a RESTful Web Service. For each HTTP method the corresponding HttpClient object you would use is listed in the following table.

Examples of usage of the four main methods (GET, POST, PUT, and DELETE) are shown below. We are also using our sample Dictionary Web Service that we have been using in other blogs and screencasts. The URL for the Web Service is btiwst.appspot.com/bti/dictionary. There is an existing client built using ExtJS also at that url.

Creating a Client

Before you can use HttpClient to send a request and process a response you need to create an HttpClient instance. Here is some quick sample code to create a suitable client for our examples.

// create a HttpParams object to customize the client
HttpParams params = new BasicHttpParams();
// Add a 20 second connection timeout, default value is infinite.
HttpConnectionParams.setConnectionTimeout(params, 20000);
// Add a 20 second timeout when waiting for data, default value is infinite.
HttpConnectionParams.setSoTimeout(params, 20000);
// create a default client using the param
DefaultHttpClient httpClient = new DefaultHttpClient(params);

GET Request

As we have blogged about previously, a GET request is used to read data from a server. In our examples we are handling data in the JSON format.

Word word = null;
// create a HttpGet object with the full URI
HttpGet get = new HttpGet(dictionaryServiceUrl + "/" + name);
// tell the server you want a json response
get.addHeader("Accept", "application/json");
try {
        // execute the GET using the previously created client
	HttpResponse resp = httpClient.execute(get);
        // make sure the response code is 200
	if (resp.getStatusLine().getStatusCode() == HttpStatus.SC_OK) {
                // get the response body
		HttpEntity entity = resp.getEntity();
               // helper function to create a Word object from json
		word = parseWord(entity);
	}
} catch (Exception e) {
	throw new DictionaryClientExcept