RestTemplate provides an abstraction for making RESTful HTTP requests, and internally, RestTemplate utilizes a native Android HTTP client library for those requests. There are two native HTTP clients available on Android, the standard J2SE facilities, and the HttpComponents HttpClient. The standard JS2SE facilities are made available through the SimpleClientHttpRequestFactory, while the HttpClient is made available through the HttpComponentsClientHttpRequestFactory. The default ClientHttpRequestFactory used when you create a new RestTemplate instance differs based on the version of Android on which your application is running.

Google recommends to use the J2SE facilities on Gingerbread (Version 2.3) and newer, while previous versions should use the HttpComponents HttpClient. Based on this recommendation RestTemplate checks the version of Android on which your app is running and uses the appropriate ClientHttpRequestFactory. To utilize a specific ClientHttpRequestFactory you must either pass a new instance into the RestTemplate constructor, or call setRequestFactory(ClientHttpRequestFactory requestFactory) on an existing RestTemplate instance.

RestTemplate supports sending and receiving data encoded with gzip compression. The HTTP specification allows for additional values in the Accept-Encoding header field, however RestTemplate only supports gzip compression at this time.

Object to JSON marshaling in Spring for Android RestTemplate requires the use of a third party JSON mapping library. There are three libraries supported in Spring for Android, Jackson JSON Processor, Jackson 2.x, and Google Gson. While Jackson is a well known JSON parsing library, the Gson library is smaller, which would result in an smaller Android app when packaged.

Object to XML marshaling in Spring for Android RestTemplate requires the use of a third party XML mapping library. The Simple XML serializer is used to provide this marshaling functionality.

RSS and Atom feed support in Spring for Android RestTemplate requires the use of a third party feed reader library. The Android ROME Feed Reader is used to provide this functionality.

In order to use RestTemplate in your Android application, you must include the following Spring for Android jars in the libs/ folder. These are available from the SpringSource Community Downloads page.

If you are building your project with Ant, Ant will automatically include any jars located in the libs/ folder located in the root of your project. However, in Eclipse you must manually add the jars to the Build Path. Follow these steps to add the jars to your existing Android project in Eclipse.

Google's provided Android toolset does not include dependency management support. However, through the use of third party tools, you can use Maven to manage dependencies and build your Android app. See the Spring for Android and Maven section for more information. Additional dependencies may be required, depending on which HTTP Message Converters you are using within RestTemplate. See the Message Converters section for more information.

Add the spring-android-rest-template artifact to your classpath:

<dependency>
    <groupId>org.springframework.android</groupId>
    <artifactId>spring-android-rest-template</artifactId>
    <version>${spring-android-version}</version>
</dependency>
			

The transitive dependencies are automatically imported by Maven, but they are listed here for clarity.

<dependency>
    <groupId>org.springframework.android</groupId>
    <artifactId>spring-android-core</artifactId>
    <version>${spring-android-version}</version>
</dependency>
			

public void delete(String url, Object... urlVariables) throws RestClientException;

public void delete(String url, Map<String, ?> urlVariables) throws RestClientException;

public void delete(URI url) throws RestClientException;
		

public <T> T getForObject(String url, Class<T> responseType, Object... urlVariables) throws RestClientException;

public <T> T getForObject(String url, Class<T> responseType, Map<String, ?> urlVariables) throws RestClientException;

public <T> T getForObject(URI url, Class<T> responseType) throws RestClientException;

public <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Object... urlVariables);

public <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map<String, ?> urlVariables);

public <T> ResponseEntity<T> getForEntity(URI url, Class<T> responseType) throws RestClientException;
		

public HttpHeaders headForHeaders(String url, Object... urlVariables) throws RestClientException;

public HttpHeaders headForHeaders(String url, Map<String, ?> urlVariables) throws RestClientException;

public HttpHeaders headForHeaders(URI url) throws RestClientException;
		

public Set<HttpMethod> optionsForAllow(String url, Object... urlVariables) throws RestClientException;

public Set<HttpMethod> optionsForAllow(String url, Map<String, ?> urlVariables) throws RestClientException;

public Set<HttpMethod> optionsForAllow(URI url) throws RestClientException;
		

public URI postForLocation(String url, Object request, Object... urlVariables) throws RestClientException;

public URI postForLocation(String url, Object request, Map<String, ?> urlVariables);

public URI postForLocation(URI url, Object request) throws RestClientException;

public <T> T postForObject(String url, Object request, Class<T> responseType, Object... uriVariables);

public <T> T postForObject(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables);

public <T> T postForObject(URI url, Object request, Class<T> responseType) throws RestClientException;

public <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Object... uriVariables);

public <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException;

public <T> ResponseEntity<T> postForEntity(URI url, Object request, Class<T> responseType) throws RestClientException;
		

public void put(String url, Object request, Object... urlVariables) throws RestClientException;

public void put(String url, Object request, Map<String, ?> urlVariables) throws RestClientException;

public void put(String url, Object request, Map<String, ?> urlVariables) throws RestClientException;
		

For performance reasons, the default RestTemplate constructor does not register any message converters. However, if you pass true to the alternate constructor, then converters for the main mime types are registered. You can also write your own converter and register it via the messageConverters property.

When using the alternate RestTemplate constructor, the default converter instances registered with the template are ByteArrayHttpMessageConverter, StringHttpMessageConverter, and ResourceHttpMessageConverter. If your app is running on Android 2.2 or later, then XmlAwareFormHttpMessageConverter and SourceHttpMessageConverter are registered, as these two message converters require javax.xml.transform.Source. On Android 2.1, this falls back to the FormHttpMessageConverter which lacks some of the XML support in the other two. See the following table for more information.

The following HttpMessageConverter implementations are available in Spring for Android. For all converters a default media type is used but can be overridden through the supportedMediaTypes property.

<dependency>
    <groupId>org.simpleframework</groupId>
    <artifactId>simple-xml</artifactId>
    <version>${simple-version}</version>
</dependency>
			

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>${jackson-version}</version>
</dependency>
			

<dependency>
    <groupId>org.codehaus.jackson</groupId>
    <artifactId>jackson-mapper-asl</artifactId>
    <version>${jackson-version}</version>
</dependency>
			

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>${gson-version}</version>
</dependency>
			

<dependency>
    <groupId>com.google.code.android-rome-feed-reader</groupId>
    <artifactId>android-rome-feed-reader</artifactId>
    <version>${android-rome-version}</version>
</dependency>
			

<dependency>
    <groupId>org.jdom</groupId>
    <artifactId>jdom</artifactId>
    <version>${jdom-fork-version}</version>
</dependency>
			

<!-- For developing with Android ROME Feed Reader -->
<repository>
    <id>android-rome-feed-reader-repository</id>
    <name>Android ROME Feed Reader Repository</name>
    <url>https://android-rome-feed-reader.googlecode.com/svn/maven2/releases</url>
</repository>
			

The following example shows a query to google for the search term "SpringSource".

String url = "https://ajax.googleapis.com/ajax/services/search/web?v=1.0&q={query}";
			
// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the String message converter
restTemplate.getMessageConverters().add(new StringHttpMessageConverter());

// Make the HTTP GET request, marshaling the response to a String
String result = restTemplate.getForObject(url, String.class, "SpringSource");
		

Gzip compression can significantly reduce the size of the response data being returned in a REST request. Gzip must be supported by the web server to which the request is being made. By setting the content coding type of the Accept-Encoding header to gzip, you are requesting that the server respond using gzip compression. If gzip is available, or enabled on the server, then it should return a compressed response. RestTemplate checks the Content-Encoding header in the response to determine if, in fact, the response is gzip compressed. At this time, RestTemplate only supports the gzip content coding type in the Content-Encoding header. If the response data is determined to be gzip compressed, then a GZIPInputStream is used to decompress it.

The following example shows how to request a gzip compressed response from the server.

// Add the gzip Accept-Encoding header
HttpHeaders requestHeaders = new HttpHeaders();
requestHeaders.setAcceptEncoding(ContentCodingType.GZIP);
HttpEntity<?> requestEntity = new HttpEntity<Object>(requestHeaders);

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the String message converter
restTemplate.getMessageConverters().add(new StringHttpMessageConverter());

// Make the HTTP GET request, marshaling the response to a String
ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.GET, requestEntity, String.class);
		

One thing to note, is that when using the J2SE facilities with the SimpleClientHttpRequestFactory, Gingerbread and newer automatically set the Accept-Encoding header to request gzip responses. This is built in functionality of newer versions of Android. If you desire to disable gzip, then you must set the identity value in the header.

// Add the identity Accept-Encoding header
HttpHeaders requestHeaders = new HttpHeaders();
requestHeaders.setAcceptEncoding(ContentCodingType.IDENTITY);
HttpEntity<?> requestEntity = new HttpEntity<Object>(requestHeaders);

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the String message converter
restTemplate.getMessageConverters().add(new StringHttpMessageConverter());

// Make the HTTP GET request, marshaling the response to a String
ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.GET, requestEntity, String.class);
		

Suppose you have defined a Java object you wish to populate from a RESTful web request that returns JSON content.

Define your object based on the JSON data being returned from the RESTful request:

public class Event {

    private Long id;

    private String title;
	
    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }
	
    public String setTitle(String title) {
        this.title = title;
    }
}
		

Make the REST request:

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the Jackson message converter
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());

// Make the HTTP GET request, marshaling the response from JSON to an array of Events
Event[] events = restTemplate.getForObject(url, Event[].class);
		

You can also set the Accept header for the request:

// Set the Accept header
HttpHeaders requestHeaders = new HttpHeaders();
requestHeaders.setAccept(Collections.singletonList(new MediaType("application","json")));
HttpEntity<?> requestEntity = new HttpEntity<Object>(requestHeaders);

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the Jackson message converter
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());

// Make the HTTP GET request, marshaling the response from JSON to an array of Events
ResponseEntity<Event[]> responseEntity = restTemplate.exchange(url, HttpMethod.GET, requestEntity, Event[].class);
Event[] events = responseEntity.getBody();
		

Alternatively, you can use the GsonHttpMessageConverter for JSON marshaling. The following repeats the same request, utilizing Gson.

// Set the Accept header
HttpHeaders requestHeaders = new HttpHeaders();
requestHeaders.setAccept(Collections.singletonList(new MediaType("application","json")));
HttpEntity<?> requestEntity = new HttpEntity<Object>(requestHeaders);

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the Gson message converter
restTemplate.getMessageConverters().add(new GsonHttpMessageConverter());

// Make the HTTP GET request, marshaling the response from JSON to an array of Events
ResponseEntity<Event[]> responseEntity = restTemplate.exchange(url, HttpMethod.GET, requestEntity, Event[].class);
Event[] events = responseEntity.getBody();
		

Using the same Java object we defined earlier, we can modify the requests to retrieve XML.

Define your object based on the XML data being returned from the RESTful request. Note the annotations used by Simple to marshal the object:

@Root
public class Event {

    @Element
    private Long id;

    @Element
    private String title;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }

    public String setTitle(String title) {
        this.title = title;
    }
}
		

To marshal an array of events from xml, we need to define a wrapper class for the list:

@Root(name="events")
public class EventList {

   @ElementList(inline=true)
   private List<Event> events;

   public List<Event> getEvents() {
      return events;
   }

   public void setEvents(List<Event> events) {
       this.events = events;
   }
}
		

Make the REST request:

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the Simple XML message converter
restTemplate.getMessageConverters().add(new SimpleXmlHttpMessageConverter());

// Make the HTTP GET request, marshaling the response from XML to an EventList object
EventList eventList = restTemplate.getForObject(url, EventList.class);
		

You can also specify the Accept header for the request:

// Set the Accept header
HttpHeaders requestHeaders = new HttpHeaders();
requestHeaders.setAccept(Collections.singletonList(new MediaType("application","xml")));
HttpEntity<?> requestEntity = new HttpEntity<Object>(requestHeaders);

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the Simple XML message converter
restTemplate.getMessageConverters().add(new SimpleXmlHttpMessageConverter());

// Make the HTTP GET request, marshaling the response from XML to an EventList
ResponseEntity<EventList> responseEntity = restTemplate.exchange(url, HttpMethod.GET, requestEntity, EventList.class);
EventList eventList = responseEntity.getBody();
		

POST a Java object you have defined to a RESTful service that accepts JSON data.

Define your object based on the JSON data expected by the RESTful request:

public class Message 
{
    private long id;

    private String subject;

    private String text;

    public void setId(long id) {
        this.id = id;
    }

    public long getId() {
        return id;
    }

    public void setSubject(String subject) {
        this.subject = subject;
    }

    public String getSubject() {
        return subject;
    }

    public void setText(String text) {
        this.text = text;
    }

    public String getText() {
        return text;
    }
}
		

Make the REST request. In this example, the request responds with a string value:

// Create and populate a simple object to be used in the request
Message message = new Message();
message.setId(555);
message.setSubject("test subject");
message.setText("test text");

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the Jackson and String message converters
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
restTemplate.getMessageConverters().add(new StringHttpMessageConverter());

// Make the HTTP POST request, marshaling the request to JSON, and the response to a String
String response = restTemplate.postForObject(url, message, String.class);
		

You can also specify the Content-Type header in your request:

// Create and populate a simple object to be used in the request
Message message = new Message();
message.setId(555);
message.setSubject("test subject");
message.setText("test text");

// Set the Content-Type header
HttpHeaders requestHeaders = new HttpHeaders();
requestHeaders.setContentType(new MediaType("application","json"));
HttpEntity<Message> requestEntity = new HttpEntity<Message>(message, requestHeaders);

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the Jackson and String message converters
restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
restTemplate.getMessageConverters().add(new StringHttpMessageConverter());

// Make the HTTP POST request, marshaling the request to JSON, and the response to a String
ResponseEntity<String> responseEntity = restTemplate.exchange(url, HttpMethod.POST, requestEntity, String.class);
String result = responseEntity.getBody();
		

The following is a basic example of loading an RSS feed:

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the ROME message converter
restTemplate.getMessageConverters().add(new SyndFeedHttpMessageConverter());

// Make the HTTP GET request, marshaling the response to a SyndFeed object
SyndFeed = restTemplate.getForObject(url, SyndFeed.class);
		

It is possible that you need to adjust the Media Type associated with the SyndFeedHttpMessageConverter. By default, the converter is associated with application/rss+xml and application/atom+xml. An RSS feed might instead have a media type of text/xml, for example. The following code illustrates how to set the media type.

// Set the alternate mime type for the message converter
SyndFeedHttpMessageConverter syndFeedConverter = new SyndFeedHttpMessageConverter();
syndFeedConverter.setSupportedMediaTypes(Collections.singletonList(MediaType.TEXT_XML));

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the ROME message converter
restTemplate.getMessageConverters().add(syndFeedConverter);

// Make the HTTP GET request, marshaling the response to a SyndFeed object
SyndFeed feed = restTemplate.getForObject(url, SyndFeed.class);
		

This example illustrates how to populate the HTTP Basic Authentication header with the username and password. If the username and password are accepted, then you will receive the response from the request. If they are not accepted, then the server is supposed to return an HTTP 401 Unauthorized response. Internally, RestTemplate handles the response, then throws an HttpClientErrorException. By calling getStatusCode() on this exception, you can determine the exact cause and handle it appropriately.

// Set the username and password for creating a Basic Auth request
HttpAuthentication authHeader = new HttpBasicAuthentication(username, password);
HttpHeaders requestHeaders = new HttpHeaders();
requestHeaders.setAuthorization(authHeader);
HttpEntity<?> requestEntity = new HttpEntity<Object>(requestHeaders);

// Create a new RestTemplate instance
RestTemplate restTemplate = new RestTemplate();

// Add the String message converter
restTemplate.getMessageConverters().add(new StringHttpMessageConverter());

try {
    // Make the HTTP GET request to the Basic Auth protected URL
    ResponseEntity<Message> response = restTemplate.exchange(url, HttpMethod.GET, requestEntity, String.class);
    return response.getBody();
} catch (HttpClientErrorException e) {
    Log.e(TAG, e.getLocalizedMessage(), e);
    // Handle 401 Unauthorized response
}