How to use a web API from your Android app

There are many times when your Android app will need to fetch data from the internet, to provide users with fresh information and/or data. There are different ways your app could achieve this. You could set up your own web service/API, or you could be fetching from an already existing service/API. In this article, we discuss how to use a web API from within your Android app, to fetch data for your users.

There are two major methods for retrieving data from most web services, XML or JSON. XML stand for eXtensible Markup Language, and its syntax somewhat resembles HTML (Hyper Text Markup Language), in that they are both markup languages. Sample XML representation of a human can be

<human>
<sex>Male</sex>
<age>27</age>
<occupation>Software Developer</occupation>
</human>

or

<human sex="Male", age="27", occupation="Software Developer" />

JSON stands for JavaScript Object Notation, which is a nod to the fact that it is a syntax that was developed for the Javascript language, as a means of parsing Objects between programs. JSON has a comparatively standardized syntax, compared to XML, and the above XML human can be represented in JSON as

human: sex:"Male", age:"27", occupation:"Software Developer"

For this article/tutorial, we have elected to fetch data from a web service in JSON format. For simplicity sake, our app will be a simple one activity app, with a single EditText for input, a Button to initiate the web request, and a TextView to display the response.

First things first, we have to find an adequate web API from which to fetch data. After a fair bit of hunting, we settled on FullContact Person API. This is an excellent and interesting API. It takes a person’s email address, and then returns information about the person from over 120 different social networks, including facebook, twitter and linkedin. The returned information format can either be in XML or JSON. Like most API’s, you would need an API key, which must be specified with every API query. As at the time of writing, you can easily register as a developer for a free quota (trial), with a limit of 250 queries monthly. Before we begin, visit the Full Contact Developer page and get your API key.

Get an API key

While some web APIs do not require an API key, you would be hard pressed to find one that provides any useful/interesting service and doesn’t require an API key. The API key should be thought of as your unique identifier to the API provider.

For your fullcontact API key, visit the developer site and register, and you should get an email that contains your key. Ensure that you keep your API key private, to prevent others from using your key and exceeding your quota.

AndroidManifest.xml

Our application requires internet access, so we must request for the INTERNET permission in the AndroidManifest.xml file. Note that the permissions request comes before the application tags.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.sample.foo.simplewebapi" >

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

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >

        <activity
            android:name=".MainActivity"
            android:label="@string/title_activity_main" >
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

Activity Layout

We implement a very simple layout. There’s an EditText, where the person’s email address is input, and a Button to send the API query. Beneath these, we have a TextView (wrapped in a ScrollView) which would display the received JSON string, and a ProgressBar that’s initially set to be invisible using android:visibility=”gone”. The progressBar becomes visible when the “Search” Button is clicked, and disappears again when the data is about to be displayed.

<LinearLayout xmlns:android="http://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:paddingLeft="@dimen/activity_horizontal_margin"
    android:paddingRight="@dimen/activity_horizontal_margin"
    android:paddingTop="@dimen/activity_vertical_margin"
    android:paddingBottom="@dimen/activity_vertical_margin"
    tools:context="com.sample.foo.simplewebapi.MainActivity">
    <EditText
        android:id="@+id/emailText"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:inputType="textEmailAddress"
        android:hint="Enter email address"/>
    <Button
        android:id="@+id/queryButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="end"
        style="@style/Base.Widget.AppCompat.Button.Borderless"
        android:text="Search"/>
    <RelativeLayout
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        android:gravity="center">
        <ProgressBar
            android:id="@+id/progressBar"
            android:layout_width="wrap_content"
            android:layout_height="wrap_content"
            android:indeterminate="true"
            android:layout_centerHorizontal="true"
            android:visibility="gone" />
        <ScrollView
            android:layout_width="match_parent"
            android:layout_height="match_parent">
            <TextView
                android:id="@+id/responseView"
                android:layout_width="wrap_content"
                android:layout_height="wrap_content" />
        </ScrollView>
    </RelativeLayout>
</LinearLayout>

MainActivity

Before we jump into the code, there’s a very important point to note. Prior to Ice Cream Sandwich, Android apps could open a network connection, and request network resources from the main UI thread. This led to such situations where the application would be completely unresponsive while waiting for a response. Now, with stricter rules regarding performing potentially expensive operations on the UI thread, network operations must be performed on another thread. Luckily, there is a class just for this, called AsyncTask. From the Android documentation, AsyncTask facilitates the proper and easy use of the UI thread, by allowing the performance of background operations, and publishing the results on the UI thread without the need for manipulating threads and handlers. In simple words, AsyncTask handles all the complexity for you.

To make use of the AsyncTask features, you must subclass it, and provide 3 generic types, called Params, Progress and Result. Params refers to the parameters that would be parsed to your Task, Progress refers to the progress indicator/counter type, and Result is what would be returned on completion of the task. AsyncTask has 4 important methods, onPreExecute (what to do before the expensive task begins), doInBackground (the actual expensive operation goes in here), onProgressUpdate (what to do to show progress), and onPostExecute (what to do when the task is complete).

    class RetrieveFeedTask extends AsyncTask<Void, Void, String> 

        private Exception exception;

        protected void onPreExecute() 
            progressBar.setVisibility(View.VISIBLE);
            responseView.setText("");
        

        protected String doInBackground(Void... urls) 
            String email = emailText.getText().toString();
            // Do some validation here

            try 
                URL url = new URL(API_URL + "email=" + email + "&apiKey=" + API_KEY);
                HttpURLConnection urlConnection = (HttpURLConnection) url.openConnection();
                try 
                    BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(urlConnection.getInputStream()));
                    StringBuilder stringBuilder = new StringBuilder();
                    String line;
                    while ((line = bufferedReader.readLine()) != null) 
                        stringBuilder.append(line).append("n");
                    
                    bufferedReader.close();
                    return stringBuilder.toString();
                
                finally
                    urlConnection.disconnect();
                
            
            catch(Exception e) 
                Log.e("ERROR", e.getMessage(), e);
                return null;
            
        

        protected void onPostExecute(String response) 
            if(response == null) 
                response = "THERE WAS AN ERROR";
            
            progressBar.setVisibility(View.GONE);
            Log.i("INFO", response);
            responseView.setText(response);
        
    

From the code above, RetrieveFeedTask extends AsyncTask<Void, Void, String>, which indicates the type of Params is Void, Progress is Void and Result is String.

In onPreExecute, we set the ProgressBar to become visible, and we clear the contents of the TextView. This is done before the task begins running.

doInBackground expects Params, which is Void in this particular case. We then set up and open a HttpURLConnection to make an API request. The URL is built from the supplied email, and our API_KEY. Some web APIs support sending the API_KEY through a HTTP header to prevent snooping. This improves security, since an API key sent via the URL can be snooped even though the request is a HTTPS request. Finally, we read the complete response string, using a BufferedReader and a StringBuilder.

The onPostExecute method hides the ProgressBar once more, and displays the fetched response in the TextView.

Final Words

There are a ton of web APIs that provide free/trial quotas. If looking for other web APIs, two great places to begin your search include ProgrammableWeb and Mashape.

Finally, we completely ignored the fact that, to do anything useful with the returned JSON string, you will most likely need to parse the string into a Java Object. There are different libraries for manipulating and using JSON objects (E.g GSON and Jackson). However, there is the equally straightforward (and built into android) org.json package. To parse the returned string into a JSONObject can be achieved with the following code snippet.

            try 
                JSONObject object = (JSONObject) new JSONTokener(response).nextValue();
                String requestID = object.getString("requestId");
                int likelihood = object.getInt("likelihood");
                JSONArray photos = object.getJSONArray("photos");
                .
                .
                .
                .
             catch (JSONException e) 
                // Appropriate error handling code
            

As usual, the complete code is available on github for you to do with as you please.

Android Developer Newsletter

Do you want to know more? Subscribe to our Android Developer Newsletter. Just type in your email address below to get all the top developer news, tips & links once a week in your inbox. No spam, ever, just Android Dev Weekly:
Email:

Mobile operating systems and fragmentation: the insider’s point of view

If you are developing a mobile phone app you will probably ask yourself the question, how many different kinds of devices will be running my app? The answer depends on your target audience, and on what you count as a “kind of device.” But with 4,000 different kinds of devices running Android, the answer will be a fairly high number. Compare this with a similar count for Apple’s iOS operating system, where the number of device models is less than 30.

There’s no doubt about it, the Android world is diverse. For consumers that means choice and freedom, but developers can see it as fragmentation. Several companies offer services to test apps on hundreds of devices at once, and there are also other ways to economically test your apps on a range of devices. Google is also joining the fray with its new Cloud Test Lab.

As part of this year’s Google I/O conference, I waited for three hours in 55^oF weather (late May in San Francisco) to get into an independent vendor’s social event. To pass the time, I asked two Android experts about their experiences with fragmentation in the mobile space. Their responses surprised me. With their permission, I recorded parts of the conversation and transcribed it (actually, paraphrased it) for presentation in this article.

One of the experts is an Android developer for a mobile software company. The other is a high-level employee of a prominent wireless phone service provider (a “carrier” company). Both told me that they’d feel more comfortable if I don’t use their names in this article. Here’s what the Android developer said about fragmentation, and about mobile operating systems in general:

“I don’t think too much about fragmentation because we build our apps to scale. The only issues I’ve run into recently are where we don’t have enough available memory (to load large images, for example). Google implemented density-independent pixels for a reason — to scale between different screen sizes. That’s one issue. The other issue is the API levels issue. Google has appcompat to help with that. There are other things out there you can use.”

What they said

What about different phone manufactures and different hardware?”

“You mean Samsung versus LG and things like that? That comes down to hardware. Sometimes there’s something weird going on with the GPU. We try to code around it. Sometimes it ends up being something the manufacturer has to fix in a firmware update.”

So, from this developer’s point of view, Android’s fragmentation isn’t a big deal. The carrier company employee had a lot more to say. But again, it wasn’t what I was expecting to hear:

“Carriers control the ecosystem. We control the hardware, the specs, and how things are mapped out. We even control the OS. We tell Google and Microsoft (and to some extent, Apple) what kinds of APIs have to be there. So we force standardization.”

I understand that carriers outside the United States have different relationships with their customers and their governments. So I asked if these claims about the carriers’ power apply to carriers in other countries.

I don’t think too much about fragmentation because we build our apps to scale.

“It depends on the size of the carrier. When I go to the big carrier summits, everyone’s there. That is, everyone that matters is there. When Google, Microsoft, Apple, Mozilla or anyone releases an operating system with an API update or a new version, everyone’s at the table.

“At this point, 8 or 9 years into Android, we’ve worked around the issue of fragmentation. We don’t deal with screen size issues anymore. The development paradigms that have evolved are dynamic. We’ve worked on Brew, Symbian and a dozen other platforms. We’ve always dealt with screen size issues and compatibility.

“The issue that we have is a kind of reverse fragmentation. Google has been closing up its model. They’ve been under scrutiny so they’ve been taking away APIs. For instance, you don’t have direct access to NFC anymore. You can’t send and receive an SMS from an app that’s not a default SMS app. The same thing happened with mobile payments.”

I asked about an app that I created recently. My ordinary app sent an SMS using only android.permission.SEND_SMS.

“You can send an SMS for now. But you can’t sniff the traffic and you don’t have access to the call log.

“Things have been closing down. We deal with fragmentation when our clients have certain abilities and then we release a new client with a stripped down set of capabilities. (We use the word “client” interchangeably with “build.” It’s a mobile client that interacts with a server component.) We don’t like taking away features from a user who’s accustomed to having those features, especially when those features are generating revenue for that device.”

What about iOS fragmentation?

“With iOS, fragmentation is a completely different beast. Sometimes you do have to have multiple clients. Apple controls the hardware, so they haven’t evolved certain features. And certain features come late. You work around it. Apple is also much less forgiving and less willing to work with you on a lot of these things. But that’s how it goes.

“Apple doesn’t like to work with carriers or major app developers (companies that help create their ecosystem). They’ll pick out their favorite partners and work with them. But the people at Apple know what they want to do and there’s no changing it. You can request APIs but you have to fight really hard to get them. If you would like to do something more and they haven’t planned on it or they don’t want to do it, it’s not going to happen. If something is going to happen which will break functionality, you have to live with it.”

Android has evolved paradigms and frameworks that deal with backwards compatibility. It’s built into the operating system.

I asked about backwards compatibility – an issue that can affect all developers, including Android and iOS developers.

“We don’t deal with backwards compatibility. Android has evolved paradigms and frameworks that deal with backwards compatibility. It’s built into the operating system.

“Apple’s iOS has gone in the reverse. They’ve had to build up to it. For iOS, we don’t deal with API variability as much because you see 95% user adoption on day one of their new OS rollout. So you don’t really worry about backwards compatibility. The people who have that backwards compatibility issue are so much in the minority that it’s not worth targeting them. You don’t get ROI [Return on Investment] on it.”

What about Microsoft?

“For now, Microsoft is the third player in the game. Every year and half Microsoft does a complete reset on its environment. First they had Pocket PC and then Windows Mobile. But Windows 8, 8.1 and 10 have been OS releases on mobile as well as the desktop. Windows Phone 8 had Windows RT. It was running their encapsulated runtime for desktop and they had about 60% API coverage of desktop on mobile. It was a complete start-over.

But we’ve heard the ‘write it once’ claim before. With Windows 10 they officially have one operating system on Xbox, on tablets, on desktops and now phones. We’ll see.

“They’ve gone from Windows Mobile to Windows 8/8.1, and now they’re jumping to Windows 10. From a carrier’s perspective, each is a complete rewrite and a brand new framework. It’s like switching operating systems every single time. A few months back they announced a Universal Windows Platform (the UWP framework) that’s supposed to fix things so you’ll write it once and it’ll work everywhere. But we’ve heard the ‘write it once’ claim before. With Windows 10 they officially have one operating system on Xbox, on tablets, on desktops and now phones. We’ll see.”

To what extent do Windows phones play a role in your company’s planning?

“From a carrier perspective, we don’t want only two players. We want many players. We want a very rich ecosystem. Otherwise it becomes a very caustic environment where everybody is going one way. We try to level the playing field and standardize the way things are done.”

Android Developer Newsletter

Do you want to know more? Subscribe to our Android Developer Newsletter. Just type in your email address below to get all the top developer news, tips & links once a week in your inbox. No spam, ever, just Android Dev Weekly:

Email:

Wrap up

Do you have any final thoughts?

“When you choose a carrier, you want the experience with that carrier to be uniform across multiple devices. You want your contacts to work on Windows, Apple, Android, Brew, Symbian, Firefox, Tizen, and all other phones. If you get a new phone, you want to be able to access your account the same way and dial phone numbers the same way. You want voice mail to work the same way and to have the same call quality. A carrier’s goal is to provide this seamless experience to the consumer. Achieving this is a struggle.  It’s a huge effort.”

What do you think?
Are you surprised by the responses of these two industry insiders? Do you think carriers are interfering, do they have too much power? What about fragmentation? Please let us know in the comment section below.