RestClientTemplate

Overview

RestClientTemplate is a skeleton Android project that makes writing Android apps sourced from OAuth JSON REST APIs as easy as possible. This skeleton project combines the best libraries and structure to enable quick development of rich API clients. The following things are supported out of the box:

• Authenticating with any OAuth 1.0a or OAuth 2 API
• Sending requests for and parsing JSON API data using a defined client
• Persisting data to a local SQLite store through an ORM layer
• Displaying and caching remote image data into views

The following libraries are used to make this possible:

• scribe-java - Simple OAuth library for handling the authentication flow.
• Android Async HTTP - Simple asynchronous HTTP requests with JSON parsing
• codepath-oauth - Custom-built library for managing OAuth authentication and signing of requests
• UniversalImageLoader - Used for async image loading and caching them in memory and on disk.
• ActiveAndroid - Simple ORM for persisting a local SQLite database on the Android device

Usage

1. Configure the REST client

Open src/com.codepath.apps.restclienttemplate/RestClient.java. Configure the REST_API_CLASS, REST_URL, REST_CONSUMER_KEY, REST_CONSUMER_SECRET based on the values needed to connect to your particular API. The REST_URL should be the base URL used for connecting to the API (i.e https://api.twitter.com). The REST_API_CLASS should be the class defining the service you wish to connect to. Check out the full list of services you can select (i.e FlickrApi.class).

For example if I wanted to connect to Twitter:

// RestClient.javapublicclassRestClientextendsOAuthBaseClient {
publicstaticfinalClass<? extendsApi> REST_API_CLASS = TwitterApi.class;
publicstaticfinalStringREST_URL = "http://api.twitter.com";
publicstaticfinalStringREST_CONSUMER_KEY = "57fdgdfh345195e071f9a761d763ca0";
publicstaticfinalStringREST_CONSUMER_SECRET = "d657sdsg34435435";
// ...constructor and endpoints
}

Next, change the REST_CALLBACK_URL to a unique name that is special for this application. This is used for the OAuth authentication flow:

// RestClient.javapublicstaticfinalStringREST_CALLBACK_URL = "oauth://codepathtweets"; 

Also, be sure to change this value in the AndroidManifest.xml to match the same host:

// AndroidManifest.xml// manifest => application => activity
<intent-filter>
<actionandroid:name="android.intent.action.VIEW" />
<categoryandroid:name="android.intent.category.DEFAULT" />
<categoryandroid:name="android.intent.category.BROWSABLE" />
<dataandroid:host="codepathtweets"android:scheme="oauth" />
</intent-filter>

Next, you want to define the endpoints which you want to retrieve data from or send data to within your client:

// RestClient.javapublicvoidgetHomeTimeline(intpage, AsyncHttpResponseHandlerhandler) {
StringapiUrl = getApiUrl("statuses/home_timeline.json");
RequestParamsparams = newRequestParams();
params.put("page", String.valueOf(page));
getClient().get(apiUrl, params, handler);
}

Note we are using getApiUrl to get the full URL from the relative fragment and RequestParams to control the request parameters. You can easily send post requests (or put or delete) using a similar approach:

// RestClient.javapublicvoidpostTweet(Stringbody, AsyncHttpResponseHandlerhandler) {
StringapiUrl = getApiUrl("statuses/update.json");
RequestParamsparams = newRequestParams();
params.put("status", body);
getClient().post(apiUrl, params, handler);
}

These endpoint methods will automatically execute asynchronous requests signed with the authenticated access token. To use JSON endpoints, simply invoke the method with a JsonHttpResponseHandler handler:

// SomeActivity.javaRestClientclient = RestClientApp.getRestClient();
client.getHomeTimeline(1, newJsonHttpResponseHandler() {
publicvoidonSuccess(JSONArrayjson) {
// Response is automatically parsed into a JSONArray// json.getJSONObject(0).getLong("id");
}
});

Based on the JSON response (array or object), you need to declare the expected type inside the OnSuccess signature i.e public void onSuccess(JSONObject json). If the endpoint does not return JSON, then you can use the AsyncHttpResponseHandler:

RestClientclient = RestClientApp.getRestClient();
client.getSomething(newAsyncHttpResponseHandler() {
@OverridepublicvoidonSuccess(Stringresponse) {
System.out.println(response);
}
});

Check out Android Async HTTP Docs for more request creation details.

2. Define the Models

In the src/com.codepath.apps.restclienttemplate.models, create the models that represent the key data to be parsed and persisted within your application. For example, if you were connecting to Twitter, you would want a Tweet model as follows:

// models/Tweet.javapackagecom.codepath.apps.restclienttemplate.models;
importorg.json.JSONException;
importorg.json.JSONObject;
importcom.activeandroid.Model;
importcom.activeandroid.annotation.Column;
importcom.activeandroid.annotation.Table;
@Table(name = "Tweets")
publicclassTweetextendsModel {
@Column(name = "userId")
StringuserId;
@Column(name = "userHandle")
StringuserHandle;
@Column(name = "timestamp")
Stringtimestamp;
@Column(name = "body")
Stringbody;
// Make sure to define this constructor with no argumentspublicTweet() {
super();
}
// And a constructor that creates an object from the JSON responsepublicTweet(JSONObjectobject){
super();
try {
this.user_id = object.getString("user_id");
// ...
} catch (JSONExceptione) {
e.printStackTrace();
}
}
}

Notice here we specify the SQLite table for a resource, the columns for that table, and a constructor for turning the JSON object fetched from the API into this object. For more information on creating a model, check out the ActiveAndroid Wiki.

3. Setup Your Authenticated Activities

Open src/com.codepath.apps.restclienttemplate/LoginActivity.java and configure the onLoginSuccess method which fires once your app has access to the authenticated API. Launch an activity and begin using your REST client:

// LoginActivity.java@OverridepublicvoidonLoginSuccess() {
Intenti = newIntent(this, TimelineActivity.class);
startActivity(i);
}

In your new authenticated activity, you can access your client anywhere with:

RestClientclient = RestClientApp.getRestClient();
client.getHomeTimeline(1, newJsonHttpResponseHandler() {
publicvoidonSuccess(JSONArrayjson) {
Log.d("DEBUG", "timeline: " + json.toString());
}
});

You can also persist data to your models using:

Tweett = newTweet();
t.user_id = json.getInteger("user_id");
t.user_handle = json.getString("user_username");
t.timestamp = json.getString("timestamp");
t.body = json.getString("body");
// or new Tweet(json);t.save();

That's all you need to get started. From here, hook up your activities and their behavior, adjust your models and add more REST endpoints.