retrofit

Class RestAdapter

java.lang.Object

retrofit.RestAdapter

public class RestAdapter
extends Object

Adapts a Java interface to a REST API.

API endpoints are defined as methods on an interface with annotations providing metadata about the form in which the HTTP call should be made.

The relative path for a given method is obtained from an annotation on the method describing the request type. The built-in methods are GET, PUT, POST, HEAD, and DELETE. You can define your own HTTP method by creating an annotation that takes a {code String} value and itself is annotated with @RestMethod.

Method parameters can be used to replace parts of the URL by annotating them with @Path. Replacement sections are denoted by an identifier surrounded by curly braces (e.g., "{foo}"). To add items to the query string of a URL use @Query.

HTTP requests happen in one of two ways:

• On the provided HTTP Executor with callbacks marshaled to the callback Executor. The last method parameter should be of type Callback. The HTTP response will be converted to the callback's parameter type using the specified Converter. If the callback parameter type uses a wildcard, the lower bound will be used as the conversion type.
• On the current thread returning the response or throwing a RetrofitError. The HTTP response will be converted to the method's return type using the specified Converter.

The body of a request is denoted by the @Body annotation. The object will be converted to request representation by a call to toBody on the supplied Converter for this instance. The body can also be a TypedOutput where it will be used directly.

Alternative request body formats are supported by method annotations and corresponding parameter annotations:

• @FormUrlEncoded - Form-encoded data with key-value pairs specified by the @Field parameter annotation.
• @Multipart - RFC 2387-compliant multi-part data with parts specified by the @Part parameter annotation.

Additional static headers can be added for an endpoint using the @Headers method annotation. For per-request control over a header annotate a parameter with @Header.

For example:

 public interface MyApi {
   @POST("/category/{cat}") // Asynchronous execution.
   void categoryList(@Path("cat") String a, @Query("page") int b,
                     Callback<List<Item>> cb);
   @POST("/category/{cat}") // Synchronous execution.
   List<Item> categoryList(@Path("cat") String a, @Query("page") int b);
 }
 

Calling create(Class) with MyApi.class will validate and create a new implementation of the API.

Author:

Bob Lee (bob@squareup.com), Jake Wharton (jw@squareup.com)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RestAdapter.Builder Build a new RestAdapter.
static interface	RestAdapter.Log Simple logging abstraction for debug messages.
static class	RestAdapter.LogLevel Controls the level of logging.

Method Summary

Modifier and Type	Method and Description
<T> T	create(Class<T> service) Create an implementation of the API defined by the specified service interface.
RestAdapter.LogLevel	getLogLevel() The current logging level.
void	setLogLevel(RestAdapter.LogLevel loglevel) Change the level of logging.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setLogLevel

public void setLogLevel(RestAdapter.LogLevel loglevel)

Change the level of logging.

getLogLevel

public RestAdapter.LogLevel getLogLevel()

The current logging level.

create

public <T> T create(Class<T> service)

Create an implementation of the API defined by the specified service interface.