How To Create Rest Api For Android App Using Java

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 theandroid.permission.INTERNET permission. Therefore, before you start writing any networking code, you must make sure that the followinguses-permission tag is present in your project's manifest file:

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

Becauseandroid.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. AnAsyncTask 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 theAsyncTask 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.

3. Creating an HTTP Connection

By using theopenConnection() method of theURL class, you can quickly set up a connection to any REST endpoint. The return value ofopenConnection() must be cast to an instance of eitherHttpURLConnection orHttpsURLConnection, depending on whether the endpoint is accessed over HTTP or HTTPS. BothHttpURLConnection andHttpsURLConnection 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 thatHttpsURLConnection is a subclass of theHttpURLConnection 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 uniqueUser-Agent header in all your requests.

To add aUser-Agent header to your request, you must use thesetRequestProperty() method of theHttpURLConnection object. For example, here's how you set theUser-Agent header tomy-rest-app-v0.1:

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

You can add multiple headers to your request by calling thesetRequestProperty() method multiple times. For example, the following code snippet adds anAccept header and a customContact-Me header:

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

5. Reading Responses

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

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

If theHttpURLConnection class gets a redirect response code, such as301, 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.

InputStream responseBody = myConnection.getInputStream();

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

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

6. Parsing JSON Responses

The Android SDK has a class calledJsonReader, which makes it very easy for you to parse JSON documents. You can create a new instance of theJsonReader class by passing theInputStreamReader 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 calledorganization_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 theclose() method theJsonReader object so that it releases all the resources it holds.

jsonReader.close();

You must also close the connection by calling thedisconnect() method of theHttpURLConnection 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 HTTPGET method to perform a read operation. Because theHttpURLConnection class uses theGET method by default, we didn't have to specify it explicitly.

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

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 thePOST request. However, before you do so, you must make sure that you call thesetDoOutput() method of theHttpURLConnection object and passtrue 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 calledHttpResponseCache, 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 theinstall() method of theHttpResponseCache 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, theHttpURLConnection class starts using it automatically. To check if your cache is working, you can use itsgetHitCount() method, which returns the number of HTTP responses that were served from the cache.

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

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.

ClickNext, 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 addINTERNET permissions in the manifest file. Go tomanifests/AndroidManifest.xml and enableINTERNET permission for the app to access API calls.

<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, usefindViewById() to hook the components on theonCreate 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 theAsyncTask 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 theonPreExecute() 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 thedoInBackground 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 theonPostExecute() 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 anonClickLIstener on the button and executeMyAsyncTasks 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 theHttpURLConnection 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 usingHttpURLConnection is hard, you should give third-party libraries such as Volley a try. Libraries like this use theHttpURLConnection 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.