All REST operations are also available for asynchronous calls. The asynchronous methods are suffixed by the word 'Async' based on common .NET naming conventions.

Note, that asynchronous call were initially added to support Silverlight and Windows Phone, but nothing prevents you from using them for Windows Forms and WPF applications to not freeze the UI when invoking RESTful services.
An example using an asynchronous method is shown below :

template.GetForObjectAsync<string>("http://example.com/hotels/bookings", 
  r =>
  {
    if (r.Error != null)
    {
      Console.WriteLine(r.Error);
    }
    else
    {
      Console.WriteLine(r.Response);
    }
  });

In some cases it may be useful to set up the base url of the request once. This is possible by setting the base address in the constructor or by setting the property BaseAddress.
For example:

RestTemplate template = new RestTemplate("http://example.com");
Booking booking1 = template.GetForObject<Booking>("/hotels/{id}/bookings", 1);
Booking booking2 = template.GetForObject<Booking>("/hotels/{id}/bookings", 2);

Objects passed to and returned from REST operations are converted to and from HTTP messages by IHttpMessageConverter instances.

Converters for the main mime types are registered by default, but you can also write your own converter and register it via the MessageConverters property.

The default converter instances registered with the template, depending of the target Framework, are ByteArrayHttpMessageConverter, StringHttpMessageConverter, FormHttpMessageConverter, XmlDocumentHttpMessageConverter, XElementHttpMessageConverter, Atom10FeedHttpMessageConverter and Rss20FeedHttpMessageConverter.

You can override these defaults using the MessageConverters property. This is required if you want to use the XmlSerializableHttpMessageConverter/DataContractHttpMessageConverter or JsonHttpMessageConverter/NJsonHttpMessageConverter.

For example :

// Add a new converter to the default list
RestTemplate template = new RestTemplate("http://twitter.com");
template.MessageConverters.Add(new JsonHttpMessageConverter());

See HTTP message conversion chapter for detailed description of each converter.

In case of an exception processing the HTTP method, an exception of the type RestClientException will be thrown. The interface IResponseErrorHandler allows you to determine whether a particular response has an error. The default implementation throws an exception when a HTTP client or server error happens (HTTP status code 4xx or 5xx).

The default behavior can be changed by plugging in another implementation into the RestTemplate via the ErrorHandler property. The example below shows a custom IResponseErrorHandler implementation which gives the user total control over the response.

public class MyResponseErrorHandler : IResponseErrorHandler
{
  public bool HasError(IClientHttpResponse response)
  {
    return false;
  }

  public void HandleError(IClientHttpResponse response)
  {
    // This method should not be called because HasError returns false.
    throw new InvalidOperationException();
  }
}

RestTemplate template = new RestTemplate("http://example.com");
template.ErrorHandler = new MyResponseErrorHandler();

HttpResponseMessage responseMessage = template.PostForMessage("/notfound", null); // throw HttpClientErrorException with default implementation
if (responseMessage.StatusCode == HttpStatusCode.NotFound)
{
  // ...
}

RestTemplate uses a request factory to create instances of the IClientHttpRequest interface. Default implementation uses the .NET Framework class HttpWebRequest. This can be overridden by specifying an implementation of IClientHttpRequestFactory via the RequestFactory property.

The default implementation WebClientHttpRequestFactory uses an instance of HttpWebRequest which can be configured with credentials information or proxy settings. An example setting the proxy is shown below :

WebClientHttpRequestFactory requestFactory = new WebClientHttpRequestFactory();
requestFactory.Proxy = new WebProxy("http://proxy.example.com:8080");
requestFactory.Proxy.Credentials = new NetworkCredential("userName", "password", "domain");

RestTemplate template = new RestTemplate("http://example.com");
template.RequestFactory = requestFactory;

RestTemplate template = new RestTemplate("http://example.com");
((WebClientHttpRequestFactory)rt.RequestFactory).WebRequestCreator = WebRequestCreatorType.ClientHttp;

RestTemplate allows you to intercept HTTP request creation and/or execution. You can create your own interceptor and register it via the RequestInterceptors property.

Four types of interceptors are provided :

An example of an interceptor measuring HTTP request execution time is shown below.

public class PerfRequestSyncInterceptor : IClientHttpRequestSyncInterceptor
{
  public IClientHttpResponse Execute(IClientHttpRequestSyncExecution execution)
  {
    Stopwatch stopwatch = Stopwatch.StartNew();   
    IClientHttpResponse response = execution.Execute();
    stopwatch.Stop();
    
    Console.WriteLine(String.Format(
      "Sync {0} request for '{1}' took {2}ms and resulted in {3:d} - {3}",
      execution.Method,
      execution.Uri,
      stopwatch.ElapsedMilliseconds, 
      response.StatusCode));
    
    return response;  
  }
}

RestTemplate template = new RestTemplate();
template.RequestInterceptors.Add(new PerfRequestSyncInterceptor());

Note that you can also make PerfRequestSyncInterceptor implement IClientHttpRequestAsyncInterceptor to support both synchronous and asynchronous requests.

RestTemplate, as any other class can be configured in the Spring.NET container.
For example, using XML configuration :

<object id="RestTemplate" type="Spring.Rest.Client.RestTemplate, Spring.Rest">
  <constructor-arg name="baseAddress" value="http://example.com"/>
  <property name="ErrorHandler">
    <object type="MyErrorHandler"/>
  </property>
  <property name="MessageConverters">
    <list>
      <object type="MyHttpMessageConverter"/>
    </list>
  </property>
  <property name="RequestInterceptors">
    <list>
      <object type="MyClientHttpRequestInterceptor"/>
    </list>
  </property>
  <property name="RequestFactory.UseDefaultCredentials" value="true"/>
  <property name="RequestFactory.Timeout" value="10000"/>
</object>

The default request factory implementation WebClientHttpRequestFactory, that uses the HttpWebRequest class, can be used to authenticate the HTTP request. Supported authentication schemes include Basic, Digest, Negotiate (SPNEGO), Kerberos, NTLM, and Certificates.

WebClientHttpRequestFactory requestFactory = new WebClientHttpRequestFactory();
requestFactory.Credentials = new NetworkCredential("userName", "password", "domain");

RestTemplate template = new RestTemplate("http://example.com");
template.RequestFactory = requestFactory;

You can also directly cast the default request factory to WebClientHttpRequestFactory :

RestTemplate template = new RestTemplate("http://example.com");
((WebClientHttpRequestFactory)template.RequestFactory).UseDefaultCredentials = true;

Basic authentication is supported by the WebClientHttpRequestFactory (see previous section), but this implementation will wait the challenge response from server before to send the 'Authorization' header value. As this can be an issue in some cases, Spring provides a custom request interceptor named BasicSigningRequestInterceptor that forces Basic authentication. This is shown below

RestTemplate template = new RestTemplate("http://example.com");
template.RequestInterceptors.Add(new BasicSigningRequestInterceptor("login", "password"));

This will be supported in a future version based on the Spring.Social Java project. The implementation is based on request interceptors.