README.md

Retrofit
========

Reusable Java and Android code from Square, Inc.

Modules:

 * http - Abstracts away the messy logic of making network calls (depends on 'io').
 * io - Utility classes for doing low-level java I/O.
 * sync - Directory write synchronization.


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.create(MyInterface.class)` will create an
instance of that API handler, which you can then store and use throughout your application.  An
example interface:

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

  // 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);
}
```

Each method has a `Callback` type specified at the end of the parameter list.  This is how your
application will handle the results of your network calls asynchronously: errors and successful
responses are both handled by the `Callback` interface.

If you want to use the `@SingleEntity` method of specifying request body (see `singleEntityPost` above),
your `MyJsonObject` will need to implement `TypedBytes`.

For synchronous execution, omit the `Callback` parameter and specify the response as the return type.

```java
public interface DummyServiceSync {
  @GET("foo/bar")
  SimpleResponse normalGet(@Named("id") String id);
}
```

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.