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/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 will usually define a ROOT_URL in @Rest annotation,

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

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

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

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("http://company.com/ajax/services")
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 define.
}

@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("http://company.com/ajax/services")
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("http://company.com/ajax/services")
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("http://company.com/ajax/services")
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("http://company.com/ajax/services")
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("http://company.com/ajax/services")
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("http://company.com/ajax/services")
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("http://company.com/ajax/services")
@Accept(MediaType.APPLICATION_XML)
public interface MyService {

}

Use your REST API

@RestService

@EActivity
public class MyActivity extends Activity {

	@RestService
	MyRestClient myRestClient; //Inject it

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

}

A Full REST API example

@Rest("http://company.com/ajax/services")
// 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);
}