Rest API

Since AndroidAnnotations 2.2

Create your REST API interface

@Rest

Rest API works with an @Rest annotated interface. It's the entry point. In a common use, you should define a BASE_URI in @Rest annotation,

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

but you can omit the BASE_URI and define a complete URI on every methods.

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

Placeholders

You can add parameters in every URI except for URI in @Rest. You've to write parameters name in brackets and you must define all of them as parameters of your method.

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

OR

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

BUT NOT

@Get("/events/{year}/{location}")
EventList getEvents(String location); //Wrong, "year" must be define.

@Get

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

Your method can return nothing,

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

or a representing class of the object contained in the HTTP response. The binding JSON/XML to Object is automatically done by the RestTemplate. You have just to add an Json Parser library in your Classpath (only Jackson or GSon).

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

You can't return a List of Object but it's possible to return an Object containing a list of Object.

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

With

public class EventList {
    private List<Event> events;
[...]

For example, whether you want check the Http header you can get the ResponseEntity, a Http Response representation.

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

@Post

Send a request with POST HTTP method.

POST HTTP method is principally used to send object in order to add it. You've just to add a parameter representing the object in your annotated method. The return types are the same as @GET.

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

OR

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

OR

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

OR

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

Of course, you can send a POST request without send any object,

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

@Put

Send a PUT HTTP Method request.

@Put annotated methods must return void.

@Put("/events")
public void updateEvent();

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

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

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

@Delete

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

@Delete("/events")
public void deleteEvent();

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

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

@Options

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

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

OR

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

@Head

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

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

@Accept

You can define the response format sent by your webservices (JSON, XML, TEXT, HTML...).

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

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

@Post("/entity")
@Accept(MediaType.APPLICATION_XML)
public 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);
}