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:

1	<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. An AsyncTask subclass has the following methods for performing work off the main thread:

onPreExecute(): This method runs on the UI thread, and is used for setting up your task (like showing a progress bar).
doInBackground(): This is where you implement the code to execute the work that is to be performed on the separate thread.
onProgressUpdate(): This is invoked on the UI thread and used for updating progress in the UI (such as filling up a progress bar).
onPostExecute(): Again on the UI thread, this is used for updating the results to the UI once the AsyncTask has finished loading.

private class MyTask extends AsyncTask<Void, Void, Void> { 
    
    
     // 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.

Android From Scratch: Background Operations

Paul Trebilcox-Ruiz

22 Jul 2016

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:

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:

1	myConnection.setRequestProperty("Accept",
2	"application/vnd.github.v3+json");
3	myConnection.setRequestProperty("Contact-Me",
4	"hathibelagal@example.com");

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.

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

1	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.

1	InputStreamReader responseBodyReader =
2	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.

1	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.

1	jsonReader.close();

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

1	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:

1	HttpResponseCache myCache = HttpResponseCache.install(
2	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.

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

How to Build an Android App With an API

Prerequisites

Before you start developing any Android app, you should install Android Studio and have the latest Android SDK installed through Android Studio.

Getting Started

Open Android Studio and create a new project with an empty activity.

Click Next, configure the settings as shown, and click Finish.

Wait a few minutes for Android Studio to create your project files. Your project structure should now look like this.

The next thing is to add INTERNET permissions in the manifest file. Go to manifests/AndroidManifest.xml and enable INTERNET permission for the app to access API calls.

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

Our app UI will consist of the following elements:

a button
a progress dialog
a text view

When the user clicks on the button, the progress dialog will display a message letting the user know the information is being processed. Once the data is fetched from the API, it will be displayed by the text view.

Open the activity_main.xml file and add the components as shown below.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="https://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
android:layout_width="match_parent"
android:layout_height="match_parent"
android:orientation="vertical"
android:padding="30dp"
tools:context=".MainActivity">

<Button
    android:id="@+id/displayData"
    android:layout_width="200dp"
    android:layout_height="wrap_content"
    android:layout_gravity="center"
    android:layout_marginTop="20dp"
    android:text="Click to Show  Users"
    android:textColor="@color/cardview_dark_background"
    android:textSize="18sp" />

<TextView
    android:id="@+id/results"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginTop="50dp"
    android:visibility="gone"
    android:textColor="@color/design_default_color_primary"
    android:textSize="18sp" />

</LinearLayout>


Define the URL and the UI components at the top of the Main_activity.java file.

public class MainActivity extends AppCompatActivity {
    
    String myUrl = "https://api.mocki.io/v1/a44b26bb";
    TextView resultsTextView;
    ProgressDialog progressDialog;
    Button displayData;
    
    
    //the rest of the code
    
    }

Next, use findViewById() to hook the components on the onCreate method.

    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        resultsTextView = (TextView) findViewById(R.id.results);
        displayData = (Button) findViewById(R.id.displayData);

    }

Defining an AsyncTask

Create the AsyncTask method for downloading network data from the API, and implement the onPreExecute(), doInBackground(), and onPostExecute() methods.

public class MyAsyncTasks extends AsyncTask<String, String, String> {


        @Override
        protected void onPreExecute() {
            super.onPreExecute();
            // display a progress dialog to show the user what is happening
            

        @Override
        protected String doInBackground(String... params) {

            // Fetch data from the API in the background.
         
        }

        @Override
        protected void onPostExecute(String s) {


      // show results 
        }

    }

On the onPreExecute() method, display a progress dialog that lets the user know what is happening.

@Override
protected void onPreExecute() {
    super.onPreExecute();
    // display a progress dialog for good user experiance
    progressDialog = new ProgressDialog(MainActivity.this);
    progressDialog.setMessage("processing results");
    progressDialog.setCancelable(false);
    progressDialog.show();
}

On the doInBackground method, create a URL connection and read the data from the API. Surround the operation with try-catch clauses to catch any exceptions that might occur when fetching data from the API.

@Override
protected String doInBackground(String... params) {

    // Fetch data from the API in the background.
    
    String result = "";
    try {
        URL url;
        HttpURLConnection urlConnection = null;
        try {
            url = new URL(myUrl);
            //open a URL coonnection

            urlConnection = (HttpURLConnection) url.openConnection();

            InputStream in = urlConnection.getInputStream();

            InputStreamReader isw = new InputStreamReader(in);

            int data = isw.read();

            while (data != -1) {
                result += (char) data;
                data = isw.read();

            }
            
            // return the data to onPostExecute method
            return result;

        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (urlConnection != null) {
                urlConnection.disconnect();
            }
        }

    } catch (Exception e) {
        e.printStackTrace();
        return "Exception: " + e.getMessage();
    }
    return result;
}

On the onPostExecute() method, dismiss the progress dialog and display the results to the user with a text view.

        @Override
        protected void onPostExecute(String s) {
            
            // dismiss the progress dialog after receiving data from API
            progressDialog.dismiss();
            try {

                JSONObject jsonObject = new JSONObject(s);

                JSONArray jsonArray1 = jsonObject.getJSONArray("users");

                JSONObject jsonObject1 =jsonArray1.getJSONObject(index_no);
                String id = jsonObject1.getString("id");
                String name = jsonObject1.getString("name");
                String my_users = "User ID: "+id+"\n"+"Name: "+name;

                //Show the Textview after fetching data
                resultsTextView.setVisibility(View.VISIBLE);
                
                //Display data with the Textview
                resultsTextView.setText(my_users);

            } catch (JSONException e) {
                e.printStackTrace();
            }
        }

Finally, set an onClickLIstener on the button and execute MyAsyncTasks when a user clicks the button.

        // implement setOnClickListener event on displayData button
        displayData.setOnClickListener(new View.OnClickListener() {
            @Override
            public void onClick(View v) {
                // create object of MyAsyncTasks class and execute it
                MyAsyncTasks myAsyncTasks = new MyAsyncTasks();
                myAsyncTasks.execute();
            }
        });

Final Result

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 and create an HTTP response cache that keeps your app's bandwidth usage low. You also learned how to fetch and display data from an API.

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.