Retrofit 2.0 tutorial with sample application

compile 'com.squareup.retrofit:retrofit:2.0.0-beta1'
compile 'com.squareup.retrofit:converter-gson:2.0.0-beta1'

Model

public class User {
public class User {
    public final String username;
    public final String name;
 
    public User(final String username, final String name) {
        this.username = username;
        this.name = name;
    }
}

public interface APIService {
    @POST("/api/user")
    Call<User> createUser(@Body User user);
 
    @GET("/api/user")
    Call<List<User>> users();
}

The first call creates the POST request to the REST endpoint that creates new user according to the user object provided as a parameter. @Body denotes that the parameter provided after it acts as the request body of post request.  There are other kinds of annotations available to use as a parameter. For example, to create a dynamic URL, you could use @Path annotation. Here is the list of some of the annotations and their use cases.

public class RestClient{
 
    private static RestClient instance = null;
 
    private ResultReadyCallback callback;
 
    private static final String BASE_URL = "http://10.0.2.2:8080";
    private APIService service;
    List<User> users = null;
    boolean success = false;
 
 
    public RestClient() {
        Retrofit retrofit = new Retrofit.Builder()
                .addConverterFactory(GsonConverterFactory.create())
                .baseUrl(BASE_URL)
                .build();
 
        service = retrofit.create(APIService.class);
    }
 
    public List<User> getUsers() {
        Call<List<User>> userlist = service.users();
        userlist.enqueue(new Callback<List<User>>() {
            @Override
            public void onResponse(Response<List<User>> response) {
                if (response.isSuccess()) {
                    users = response.body();
                    callback.resultReady(users);
                }
            }
 
            @Override
            public void onFailure(Throwable t) {
                  Log.e("REST", t.getMessage());
            }
        });
        return users;
    }
 
    public void setCallback(ResultReadyCallback callback) {
        this.callback = callback;
    }
 
    public boolean createUser(final Context ctx, User user) {
        Call<User> u = service.createUser(user);
        u.enqueue(new Callback<User>() {
            @Override
            public void onResponse(Response<User> response) {
                success = response.isSuccess();
                if(success) {
                    Toast.makeText(ctx, "User Created", Toast.LENGTH_SHORT).show();
                } else {
                    Toast.makeText(ctx, "Couldn't create user", Toast.LENGTH_SHORT).show();
                }
            }
 
            @Override
            public void onFailure(Throwable t) {
                Log.w("REST", t.getMessage());
                Toast.makeText(ctx, "Couldn't create user", Toast.LENGTH_SHORT).show();
 
            }
        });
        return success;
    }
 
    public static RestClient getInstance() {
        if(instance == null) {
            instance = new RestClient();
        }
        return instance;
    }
 
    public interface ResultReadyCallback {
        public void resultReady(List<User> users);
    }
 
}

Here callbacks are used to make the code asynchronous. There is equivalent synchronous version for calling the interface methods but here I am using asynchronous methods because android doesn’t allows network operation in its main thread. Callback class has two methods onResponse and onFailure. If the request is successful, onResponse method is called with response encapsulated in Response type. Response class has methods that give main body and other various metadata related to the request and response. The Class looks like as follows

class Response<T> {
        int code(); //returns HTTP code. e.g if success 200
        String message(); // message describing the code e.g if success OK
        Headers headers(); // HTTP headers
        boolean isSuccess(); // true if request status code is OK otherwise false
        T body(); // main body of response. It can be casted to desired model. 
                  // in our example it is casted to User type.
        ResponseBody errorBody(); // separate information about error
        com.squareup.okhttp.Response raw(); // Raw okhttp message
    }

Call.enqueue method enqueues the current request in asynchronous call queue. There is corresponding version in synchronous version Call.execute. I want to point out one possible exception when you try to execute or enqueue the request twice using same call object. For example

Call<List<User>> call = service.users();
 
// execute
Response response = call.execute();
 
// try executing once again
Response response = call.execute(); // raise IlligalStateException
 
// Instead clone the call
Call<List<User>> call2 = call.clone();
 
// and try to execute
Response response = call2.execute(); //works fine

Server Side