Rest client using Android-Annotations

In Building Android applications using Android Annotations, I briefly described the power of Android annotations and how it can be used to simplify the overall development process for Android applications. In addition to the annotations for Android SDK, Android Annotations has several annotations built for supporting spring android rest templates. This makes it very easy to write rest clients using Spring. Spring’s RestTemplate is a robust, popular Java-based REST client. The Spring for Android RestTemplate Module provides a version of RestTemplate that works in an Android environment.

For creating a rest client using Android-Annotations, all you need to do is provide a well annotated Java interface. Android-Annotations takes it from there and generates a fully working rest client implementation. The Rest API works with an @Rest annotated interface. It’s the entry point. You must define converters on this @Rest annotation, which corresponds to the Spring HttpMessageConverters that will be provided to the RestTemplate.

You will usually define a ROOT_URL in a @Rest annotation:

@Rest(rootUrl = "http://company.com/ajax/services", converters = { FormHttpMessageConverter.class, GsonHttpMessageConverter.class })
public interface MyRestClient {
    @Get("/events")
    EventList getEvents();
}

EventList here is a custom class that represents the format of data being returned from http://company.com/ajax/services/events call.

For the Spring Rest template, you need to define some message converteers that can conver objects from custom classes to the form suitable for sending the requests over the network. We will use the FromHttpMessageConverter to convert our objects to URLEncoded POST data. We will also use a GsonHttpMessageConverter to map the data to json objetcs. To use this, we also need to include the Gson api as an external library into the project.

We are done with the basic setup. Lets see how to send some requests. Declare your API endpoints in the annotated interface as below. The parameters can be specified within {...} and should exactly match the name of one of the arguments passed to the method. If you don’t know the the format of how the data will be returned, a generic Object can be used and then you can manually handle the results. (TIP: If you need to see how the response JSON string looks like, you can get it as new Gson().toJson(response) where response is the object returned from the request.)

@Get("/events/{year}/{location}")
EventList getEventsByYearAndLocationType1(int year, String location);

@Get("/events?year={year}&location={location}")
EventList getEventsByYearAndLocationType2(int year, String location);

@Get("/events?year={year}&location={location}")
Object getEventsByYearAndLocationType3(int year, String location);

Like the GET requests, it is extremely simple to send POST requests using Android-Annotations. One difference is that you need to define the parameters that you are going to send as a custom class (e.g. Event class in the example below) or if you want to control this dynamically, then a Map (e.g. a MultiValueMap). The url for the request can still be constructed in a similar fashion using the variables enclosed inside {...} and the response can be handled similarly as in GET requests.

@Post("/events")
void addEvent(Event event);

@Post("/events/{id}")
void addEventById(Event event, long id);

@Post("/authenticate/event/")
Object authenticateEventData(MultiValueMap data);

In addition to this, it is also very easy to send PUT, DELETE and other requests. For a complete list of all available annotations for REST client, refer to the cookbook.