Retrofit

Reusable Java and Android code from Square, Inc.

Modules:

• IO - Utility classes for doing low-level java I/O.
• HTTP - Abstracts away the messy logic of making network calls (depends on IO).
• Core - Some interfaces and utilities used by the other retrofit modules.
• Android - Contains two Android-specific utility classes: ShakeDetector (for detecting device shakes) and QueueFile (for storing a queue on the android file-system).

Http Usage

Create an interface for your API. You can create as many of these interfaces as you like. For each interface you create, calling RestAdapter.service(MyInterface.class) will create an instance of that API handler, which you can then store and use throughout your application. An example interface:

public interface DummyService {
  // Produces a url like "foo/bar?id=idValue".
  @GET("foo/bar")
  void normalGet(@Named("id") String id, Callback<SimpleResponse> callback);

  @GET("foo/bar")
  SimpleResponse normalGetSynchronous(@Named("id") String id) throws ResponseNotOKException;

  // Produces a url like "foo/idValue/bar?category=categoryValue".
  @GET("foo/{id}/bar")
  void getWithPathParam(@Named("id") String id, @Named("category") String category, Callback<SimpleResponse> callback);

  // Produces a url like "foo/bar/idValue" and body like "id=idValue&body=bodyValue".
  @POST("foo/bar/{id}")
  void normalPost(@Named("id") String id, @Named("body") String body, Callback<SimpleResponse> callback);

  // Produces a url like "foo/bar/idValue" and body generated by MyJsonObj.
  @POST("foo/bar/{id}")
  void singleEntityPost(@SingleEntity MyJsonObj card, @Named("id") String id, Callback<SimpleResponse> callback);
}

If the method has a Callback object at the end of the parameter list - the method will run asynchronously: errors and successful responses are both handled by the Callback interface.

If the method doesn't have a Callback' argument, it will be run synchronously on the current thread. This is useful in case you're calling multiple Http requests in a background process. Thus, saving the trouble of many Callbacks calling each other. See normalGetSynchronous` above for an example. Note: a ResponseNotOKException will be thrown in case of an error response.

If you want to use the @SingleEntity method of specifying request body (see singleEntityPost above), your MyJsonObject will need to implement TypedBytes. For convenience, you can extend GsonRequestEntity if you're just trying to send a JSON string in the request body.

Also worth noting: for POST/PUT requests using default form encoding for the request entity (see normalPost), any path parameters are also included in the request body. This is different from the behavior of GET/DELETE, where path parameters are excluded from the query string.

Compilation

Retrofit is built using Maven and there is a very minimal amount of setup required for compilation.

Two environment variables are required which point to your Android SDK and native Android SDK. A common place to put these is in a .bash_profile file in your home directory.

export ANDROID_HOME=~/dev/android-sdk
export ANDROID_NDK_HOME=~/dev/android-ndk

With these two environment variables loaded you can compile the modules and sample application by running mvn clean verify. Each module's built artifact will be in its respective target/ folder.