Android From Scratch: Using REST APIs

Most of us have developed voracious appetites for new information, what with the Internet being such an important part of our lives. Our attention spans too are shorter than ever, so building Android applications whose content is static can be a bad idea. Instead, you should consider building applications that can display fresh content every time the user opens them.

That might sound hard, but with more and more websites exposing their resources through REST APIs, it's actually quite easy. (See our Beginner’s Guide to HTTP and REST for a primer.)

In this tutorial, I'm going to show you how to use the classes and methods available in the Android SDK to connect to remote web servers and interact with them using their REST APIs.

1. Enabling Internet Access

Making use of a REST API obviously involves using the Internet. However, Android applications can access the Internet only if they have the android.permission.INTERNET permission. Therefore, before you start writing any networking code, you must make sure that the following uses-permission tag is present in your project's manifest file:

<uses-permission android:name="android.permission.INTERNET" />

Because android.permission.INTERNET is not considered a dangerous permission, you don't have to request for it during runtime on devices running API Level 23 or higher.

2. Creating Background Threads

The Android platform does not allow you to run network operations on the main thread of the application. Therefore, all your networking code must belong to a background thread. The easiest way to create such a thread is to use the execute() method of the AsyncTask class. As its only argument, execute() expects a Runnable object.

AsyncTask.execute(new Runnable() {
    @Override
    public void run() {
        // All your networking logic
        // should be here
    }
});

If you want to learn more about running operations in background threads, I suggest you read this tutorial about background operations from the Android From Scratch series.

3. Creating an HTTP Connection

By using the openConnection() method of the URL class, you can quickly set up a connection to any REST endpoint. The return value of openConnection() must be cast to an instance of either HttpURLConnection or HttpsURLConnection, depending on whether the endpoint is accessed over HTTP or HTTPS. Both HttpURLConnection and HttpsURLConnection allow you to perform operations such as adding request headers and reading responses.

The following code snippet shows you how to set up a connection with the GitHub API's root endpoint:

// Create URL
URL githubEndpoint = new URL("https://api.github.com/");

// Create connection
HttpsURLConnection myConnection =
        (HttpsURLConnection) githubEndpoint.openConnection();

Note that HttpsURLConnection is a subclass of the HttpURLConnection class.

4. Adding Request Headers

Most websites that offer REST APIs want to be able to identify your app uniquely. The easiest way to help them do so is to include a unique User-Agent header in all your requests.

To add a User-Agent header to your request, you must use the setRequestProperty() method of the HttpURLConnection object. For example, here's how you set the User-Agent header to my-rest-app-v0.1:

myConnection.setRequestProperty("User-Agent", "my-rest-app-v0.1");

You can add multiple headers to your request by calling the setRequestProperty() method multiple times. For example, the following code snippet adds an Accept header and a custom Contact-Me header:

myConnection.setRequestProperty("Accept", 
        "application/vnd.github.v3+json");
myConnection.setRequestProperty("Contact-Me", 
        "[email protected]");

5. Reading Responses

Once you have passed all the request headers, you can check if you have a valid response using the getResponseCode() method of the HttpURLConnection object.

if (myConnection.getResponseCode() == 200) {
    // Success
    // Further processing here
} else {
    // Error handling code goes here
}

If the HttpURLConnection class gets a redirect response code, such as 301, it handles it automatically and follows the redirect. Therefore, usually, you will not have to write any extra code to check for redirects.

In case of no errors, you can now call the getInputStream() method to get a reference to the input stream of the connection.

InputStream responseBody = myConnection.getInputStream();

Most REST APIs these days return data formatted as valid JSON documents. Therefore, instead of reading from the InputStream object directly, I suggest you create an InputStreamReader for it.

InputStreamReader responseBodyReader = 
        new InputStreamReader(responseBody, "UTF-8");

6. Parsing JSON Responses

The Android SDK has a class called JsonReader, which makes it very easy for you to parse JSON documents. You can create a new instance of the JsonReader class by passing the InputStreamReader object to its constructor.

JsonReader jsonReader = new JsonReader(responseBodyReader);

How you extract a specific piece of information from the JSON document depends on its structure. For example, the JSON document returned by the root endpoint of GitHub's REST API looks like this:

{
  "current_user_url": "https://api.github.com/user",
  "current_user_authorizations_html_url": "https://github.com/settings/connections/applications{/client_id}",
  "authorizations_url": "https://api.github.com/authorizations",
  "code_search_url": "https://api.github.com/search/code?q={query}{&page,per_page,sort,order}",
  "emails_url": "https://api.github.com/user/emails",
  "emojis_url": "https://api.github.com/emojis",
  "events_url": "https://api.github.com/events",
  "feeds_url": "https://api.github.com/feeds",
  "followers_url": "https://api.github.com/user/followers",
  "following_url": "https://api.github.com/user/following{/target}",
  "gists_url": "https://api.github.com/gists{/gist_id}",
  "hub_url": "https://api.github.com/hub",
  "issue_search_url": "https://api.github.com/search/issues?q={query}{&page,per_page,sort,order}",
  "issues_url": "https://api.github.com/issues",
  "keys_url": "https://api.github.com/user/keys",
  "notifications_url": "https://api.github.com/notifications",
  "organization_repositories_url": "https://api.github.com/orgs/{org}/repos{?type,page,per_page,sort}",
  "organization_url": "https://api.github.com/orgs/{org}",
  "public_gists_url": "https://api.github.com/gists/public",
  "rate_limit_url": "https://api.github.com/rate_limit",
  "repository_url": "https://api.github.com/repos/{owner}/{repo}",
  "repository_search_url": "https://api.github.com/search/repositories?q={query}{&page,per_page,sort,order}",
  "current_user_repositories_url": "https://api.github.com/user/repos{?type,page,per_page,sort}",
  "starred_url": "https://api.github.com/user/starred{/owner}{/repo}",
  "starred_gists_url": "https://api.github.com/gists/starred",
  "team_url": "https://api.github.com/teams",
  "user_url": "https://api.github.com/users/{user}",
  "user_organizations_url": "https://api.github.com/user/orgs",
  "user_repositories_url": "https://api.github.com/users/{user}/repos{?type,page,per_page,sort}",
  "user_search_url": "https://api.github.com/search/users?q={query}{&page,per_page,sort,order}"
}

As you can see, the response is just one large JSON object that contains several keys. To extract the value of the key called organization_url from it, you will have to write the following code:

jsonReader.beginObject(); // Start processing the JSON object
while (jsonReader.hasNext()) { // Loop through all keys
    String key = jsonReader.nextName(); // Fetch the next key
    if (key.equals("organization_url")) { // Check if desired key
        // Fetch the value as a String
        String value = jsonReader.nextString();
        
        // Do something with the value
        // ...
                
        break; // Break out of the loop
    } else {
        jsonReader.skipValue(); // Skip values of other keys
    }
}

The above code processes the JSON response as a stream of tokens. Therefore, it consumes very little memory. However, because it has to process every single token one after another, it can be slow while handling large responses.

After you've extracted all the required information, you must always call the close() method the JsonReader object so that it releases all the resources it holds.

jsonReader.close();

You must also close the connection by calling the disconnect() method of the HttpURLConnection object.

myConnection.disconnect();

7. Using Different HTTP Methods

HTTP-based REST interfaces use HTTP methods to determine the type of operation that has to be performed on a resource. In the previous steps, we made use of the HTTP GET method to perform a read operation. Because the HttpURLConnection class uses the GET method by default, we didn't have to specify it explicitly.

To change the HTTP method of your HttpURLConnection object, you must use its setRequestMethod() method. For example, the following code snippet opens a connection to an endpoint that belongs to httpbin.org and sets its HTTP method to POST:

URL httpbinEndpoint = new URL("https://httpbin.org/post");
HttpsURLConnection myConnection
        = (HttpsURLConnection) httpbinEndpoint.openConnection();

myConnection.setRequestMethod("POST");

As you might already know, POST requests are used to send data to the server. By writing to the output stream of the connection, you can easily add any data to the body of the POST request. However, before you do so, you must make sure that you call the setDoOutput() method of the HttpURLConnection object and pass true to it.

The following code snippet shows you how to send a simple key-value pair to the server:

// Create the data
String myData = "message=Hello";

// Enable writing
myConnection.setDoOutput(true);

// Write the data
myConnection.getOutputStream().write(myData.getBytes());

8. Caching Responses

It is always a good idea to cache HTTP responses. By doing so, you can not only reduce your app's bandwidth consumption, but also make it more responsive. From API level 13 onwards, the Android SDK offers a class called HttpResponseCache, which allows you to easily implement caching without making any changes to your networking logic.

To install a cache for your application, you must call the install() method of the HttpResponseCache class. The method expects an absolute path specifying where the cache must be installed, and a number specifying the size of the cache. You can use the getCacheDir() method if you don't want to specify the absolute path manually.

The following code snippet installs a cache whose size is 100,000 bytes:

HttpResponseCache myCache = HttpResponseCache.install(
                                getCacheDir(), 100000L);

Once the cache is installed, the HttpURLConnection class starts using it automatically. To check if your cache is working, you can use its getHitCount() method, which returns the number of HTTP responses that were served from the cache.

if (myCache.getHitCount() > 0) {
    // The cache is working
}

Conclusion

There are thousands of REST APIs available for you to freely use in your Android apps. By using them, you can make your app more informative, interesting, and feature-rich. In this tutorial, you learned how to use the HttpURLConnection class to consume such REST APIs. You also learned how to create an HTTP response cache that keeps your app's bandwidth usage low.

If you think using HttpURLConnection is hard, you should give third-party libraries such as Volley a try. Libraries like this use the HttpURLConnection class internally, but provide lots of convenient methods that allow you to make your code more concise and readable.

To learn more about networking on the Android platform, you can refer to Android's Network Operations guide.

HIGHLIGHTS OF THE DAY