7 days of WordPress plugins, themes & templates - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Code
  2. Android SDK

Android From Scratch: Using REST APIs

Scroll to top
Read Time: 11 mins
This post is part of a series called Android From Scratch.
Android From Scratch: Hardware Sensors

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:

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.

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:

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:

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:

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

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.

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.

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:

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:

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.

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

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:

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:

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:

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.

How to Build an Android App With an API


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.

new projectnew projectnew project

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.

project structureproject structureproject structure

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.

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.

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

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

Defining an AsyncTask

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

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

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.

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

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

Final Result

Android APIAndroid APIAndroid API


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.

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.