Rest API

Since AndroidAnnotations 2.2

Introduction

The REST API allows you to quickly write REST clients using clean interfaces.

It is a wrapper around the great Spring Android RestTemplate Module. As such, if you want to use the REST API, you should make sure that your application has the right Jars or Maven dependencies set.

You should also read the Spring Android RestTemplate Module Documentation, to know more about entity serialization / deserialization and how the RestTemplate works.

Create your REST API interface

@Rest

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 = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {
    @Get("/events")
    EventList getEvents();
}

but you can omit the ROOT_URL and define a complete URL on each method.

@Rest
public interface MyRestClient {
    @Get("http://company.com/ajax/services/events")
    EventList getEvents();
}

Since AndroidAnnotations 2.6

If you need different ROOT_URL values, you can add a void setRootUrl(String rootUrl) method to the interface.

@Rest(converters = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {
    @Get("/events")
    EventList getEvents();
    void setRootUrl(String rootUrl);
}

This can be useful if you need to create builds for different environments.

Placeholders

You can add URL parameters (except for the ROOT_URL in @Rest). You need to write the parameter names in brackets and you must define them all as parameters of your method.

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {

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

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

  // WRONG
  @Get("/events/{year}/{location}")
  EventList getEventsByLocation(String location); // Wrong, "year" must be defined.
}

@Get

Send a request with GET HTTP Method. The example shows the different possible return types.

Your method can return nothing,

@Get("/events/{id}")
void getEvent(long id);

or a class representing the object contained in the HTTP response. The binding from JSON/XML to Object is automatically done by the RestTemplate, please check the related documentation.

@Get("/events/{id}")
Event getEvent(long id);

You currently can't return a parameterized class (such as List<Event>) but you can return an Object wrapping this parameterized class.

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

With

public class EventList {
    private List<Event> events;
}

You can also return a ResponseEntity parameterized by the expected result type, which gives you access to to the response context. For instance, it could be useful to check the HTTP headers of the response.

@Get("/events/{year}/{location}")
ResponseEntity<Event> getEvents(String location, int year);

@Post

Send a request with POST HTTP method.

The POST HTTP method is used to add objects to a REST resource. You only need to add a parameter representing the object to your annotated method. The allowed return types are the same as @Get.

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {

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

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

  @Post("/events")
  Event addAndReturnEvent(Event event);

  @Post("/events")
  ResponseEntity<Event> addAndReturnResponseEntity(Event event);

}

Of course, you can send a POST request without sending any entity.

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

@Put

Send a PUT HTTP Method request.

@Put annotated methods must return void.

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {

  @Put("/events")
  void updateEvent(Event event);

  @Put("/events/{id}")
  void updateEventById(Event event, long id);

  @Put("/events")
  void updateEventNoEntity();

  @Put("/events/{id}")
  void updateEventNoEntityById(long id);

}

@Delete

Send a DELETE HTTP Method request. Quite similar to the @Put annotation. @Delete annotated methods must return void.

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {

  @Delete("/events")
  void deleteEvents();

  @Delete("/events/{id}")
  void deleteEventById(long id);

  @Delete("/events/{id}")
  void deleteEventWithEntityById(Event event, long id);
}

@Options

Send a OPTIONS HTTP Method request. Your method must return a set of HttpMethod.

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {

  @Options("/events")
  Set<HttpMethod> getEventOptions();

  @Options("/events/{year}/{location}")
  Set<HttpMethod> getEventOptions(String location, int year);
}

@Head

Send a HEAD HTTP Method request. @Head annotated methods must return HttpHeaders.

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {

  @Head("/events")
  HttpHeaders getEventHeader();
	
  @Head("/events/{year}/{location}")
  HttpHeaders getEventHeader2(String location, int year);

}

@Accept

You can negotiate the response format expected by your REST client (JSON, XML, TEXT, HTML...).

@Accept can only be used on @Get and @Post methods.

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
public interface MyRestClient {

  @Get("/events/{id}")
  @Accept(MediaType.APPLICATION_JSON)
  Event getEvent(long id);

  @Post("/entity")
  @Accept(MediaType.APPLICATION_XML)
  Event addEvent(Event event);

}

You can directly annotate the @Rest interface but only @Get and @Post will use it.

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
@Accept(MediaType.APPLICATION_XML)
public interface MyService {
}

Since AndroidAnnotations 2.7

@Accept accepts any String, so you can use custom formats e.g. @Accept("foo/bar").

Using your REST client

@RestService

@EActivity
public class MyActivity extends Activity {

	@RestService
	MyRestClient myRestClient; //Inject it

	@AfterViews
	void afterViews() {
		myRestClient.getEvents("fr", 2011); //Play with it
	}

}

RestTemplate

The generated implementation of your annotated interface uses Spring Android RestTemplate. If you want to configure the RestTemplate to your needs, you can add getRestTemplate() and setRestTemplate() methods:

@Rest("http://company.com/ajax/services")
public interface MyService {
	RestTemplate getRestTemplate();
	void setRestTemplate(RestTemplate restTemplate);
}

A Full REST API example

@Rest(rootUrl = "http://company.com/ajax/services", converters = { MappingJacksonHttpMessageConverter.class })
// if defined, the url will be added as a prefix to every request
public interface MyService {

	// url variables are mapped to method parameter names.
	@Get("/events/{year}/{location}")
	@Accept(MediaType.APPLICATION_JSON)
	EventList getEvents(String location, int year);

	// The response can be a ResponseEntity<T>
	@Get("/events/{year}/{location}")
	/*
	 * You may (or may not) declare throwing RestClientException (as a reminder,
	 * since it's a RuntimeException), but nothing else.
	 */
	ResponseEntity<EventList> getEvents2(String location, int year) throws RestClientException;

	// There should be max 1 parameter that is not mapped to an attribute. This
	// parameter will be used as the post entity.
	@Post("/events/")
	@Accept(MediaType.APPLICATION_JSON)
	Event addEvent(Event event);

	@Post("/events/{year}/")
	Event addEvent(Event event, int year);

	@Post("/events/")
	ResponseEntity<Event> addEvent2(Event event);

	@Post("/events/{year}/")
	@Accept(MediaType.APPLICATION_JSON)
	ResponseEntity<Event> addEvent2(Event event, int year);

	@Put("/events/{id}")
	void updateEvent(Event event, int id);

	// url variables are mapped to method parameter names.
	@Delete("/events/{id}")
	void removeEvent(long id);

	@Head("/events/{year}/{location}")
	HttpHeaders getEventHeaders(String location, int year);

	@Options("/events/{year}/{location}")
	Set<HttpMethod> getEventOptions(String location, int year);

	// if you need to add some configuration to the Spring RestTemplate.
	RestTemplate getRestTemplate();
	
	void setRestTemplate(RestTemplate restTemplate);
}